gnunet-handbook

The GNUnet Handbook
Log | Files | Refs
commit 6ee737b6eb39439214c5b29609b14f8f513573a4
parent bd251dc674bead514e7c329076c08a5d8ab676de
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Mon,  1 Aug 2022 14:00:49 +0200

move migrations

Diffstat:

Aguis/fs-gtk.rst | 126+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Mguis/gtk.rst | 1476-------------------------------------------------------------------------------


Mguis/index.rst | 1+


Aman_users/configuration.rst | 1226+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Mman_users/fs.rst | 286++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-


Mman_users/index.rst | 4++++


Aman_users/messenger.rst | 153+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Mman_users/reclaim.rst | 278+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Aman_users/vpn.rst | 179+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


9 files changed, 2252 insertions(+), 1477 deletions(-)

diff --git a/guis/fs-gtk.rst b/guis/fs-gtk.rst
@@ -0,0 +1,126 @@
+.. _GTK-User-Interface:
+
+GTK File-sharing User Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This chapter describes first steps for file-sharing with GNUnet. To
+start, you should launch ``gnunet-fs-gtk``.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
+.. _gtk_002dPublishing:
+
+Publishing
+^^^^^^^^^^
+
+To publish a file, select \"File Sharing\" in the menu bar just below
+the \"Statistics\" icon, and then select \"Publish\" from the menu.
+
+Afterwards, the following publishing dialog will appear:
+
+|image3|
+
+In this dialog, select the \"Add File\" button. This will open a file
+selection dialog:
+
+|image4|
+
+Now, you should select a file from your computer to be published on
+GNUnet. To see more of GNUnet's features later, you should pick a PNG or
+JPEG file this time. You can leave all of the other options in the
+dialog unchanged. Confirm your selection by pressing the \"OK\" button
+in the bottom right corner. Now, you will briefly see a \"Messages\...\"
+dialog pop up, but most likely it will be too short for you to really
+read anything. That dialog is showing you progress information as GNUnet
+takes a first look at the selected file(s). For a normal image, this is
+virtually instant, but if you later import a larger directory you might
+be interested in the progress dialog and potential errors that might be
+encountered during processing. After the progress dialog automatically
+disappears, your file should now appear in the publishing dialog:
+
+|image5|
+
+Now, select the file (by clicking on the file name) and then click the
+\"Edit\" button. This will open the editing dialog:
+
+|image6|
+
+In this dialog, you can see many details about your file. In the top
+left area, you can see meta data extracted about the file, such as the
+original filename, the mimetype and the size of the image. In the top
+right, you should see a preview for the image (if GNU libextractor was
+installed correctly with the respective plugins). Note that if you do
+not see a preview, this is not a disaster, but you might still want to
+install more of GNU libextractor in the future. In the bottom left, the
+dialog contains a list of keywords. These are the keywords under which
+the file will be made available. The initial list will be based on the
+extracted meta data. Additional publishing options are in the right
+bottom corner. We will now add an additional keyword to the list of
+keywords. This is done by entering the keyword above the keyword list
+between the label \"Keyword\" and the \"Add keyword\" button. Enter
+\"test\" and select \"Add keyword\". Note that the keyword will appear
+at the bottom of the existing keyword list, so you might have to scroll
+down to see it. Afterwards, push the \"OK\" button at the bottom right
+of the dialog.
+
+You should now be back at the \"Publish content on GNUnet\" dialog.
+Select \"Execute\" in the bottom right to close the dialog and publish
+your file on GNUnet! Afterwards, you should see the main dialog with a
+new area showing the list of published files (or ongoing publishing
+operations with progress indicators).
+
+.. _gtk_002dSearching:
+
+Searching
+^^^^^^^^^
+
+Below the menu bar, there are four entry widges labeled \"Namespace\",
+\"Keywords\", \"Anonymity\" and \"Mime-type\" (from left to right).
+These widgets are used to control searching for files in GNUnet. Between
+the \"Keywords\" and \"Anonymity\" widgets, there is also a big
+\"Search\" button, which is used to initiate the search. We will ignore
+the \"Namespace\", \"Anonymity\" and \"Mime-type\" options in this
+tutorial, please leave them empty. Instead, simply enter \"test\" under
+\"Keywords\" and press \"Search\". Afterwards, you should immediately
+see a new tab labeled after your search term, followed by the (current)
+number of search results --- \"(15)\" in our screenshot. Note that your
+results may vary depending on what other users may have shared and how
+your peer is connected.
+
+You can now select one of the search results. Once you do this,
+additional information about the result should be displayed on the
+right. If available, a preview image should appear on the top right.
+Meta data describing the file will be listed at the bottom right.
+
+Once a file is selected, at the bottom of the search result list a
+little area for downloading appears.
+
+.. _gtk_002dDownloading:
+
+Downloading
+^^^^^^^^^^^
+
+In the downloading area, you can select the target directory (default is
+\"Downloads\") and specify the desired filename (by default the filename
+it taken from the meta data of the published file). Additionally, you
+can specify if the download should be anonymous and (for directories) if
+the download should be recursive. In most cases, you can simply start
+the download with the \"Download!\" button.
+
+Once you selected download, the progress of the download will be
+displayed with the search result. You may need to resize the result list
+or scroll to the right. The \"Status\" column shows the current status
+of the download, and \"Progress\" how much has been completed. When you
+close the search tab (by clicking on the \"X\" button next to the
+\"test\" label), ongoing and completed downloads are not aborted but
+moved to a special \"\*\" tab.
+
+You can remove completed downloads from the \"\*\" tab by clicking the
+cleanup button next to the \"\*\". You can also abort downloads by right
+clicking on the respective download and selecting \"Abort download\"
+from the menu.
+
+That's it, you now know the basics for file-sharing with GNUnet!
+
+
diff --git a/guis/gtk.rst b/guis/gtk.rst
@@ -30,125 +30,6 @@ 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.
 
-.. _Configuring-the-Friend_002dto_002dFriend-_0028F2F_0029-mode:
-
-Configuring the Friend-to-Friend (F2F) mode
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-GNUnet knows three basic modes of operation:
-
--  In standard \"peer-to-peer\" mode, your peer will connect to any
-   peer.
-
--  In the pure \"friend-to-friend\" mode, your peer will ONLY connect to
-   peers from a list of friends specified in the configuration.
-
--  Finally, in mixed mode, GNUnet will only connect to arbitrary peers
-   if it has at least a specified number of connections to friends.
-
-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
-
-::
-
-   $ gnunet-peerinfo -sq
-
-The resulting output of this command needs to be added to your
-``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 ``friends`` file in the
-``FRIENDS`` option of the \"topology\" section.
-
-Once you have created the ``friends`` file, you can tell GNUnet to only
-connect to your friends by setting the ``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
-``MINIMUM-FRIENDS`` to zero and ``FRIENDS_ONLY`` to NO. This is the
-default.
-
-.. _Configuring-the-hostlist-to-bootstrap:
-
-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 ``[hostlist]``-section in your
-configuration file. You have to set the argument ``-b`` in the options
-line:
-
-::
-
-   [hostlist]
-   OPTIONS = -b
-
-Additionally you have to specify which server you want to use. The
-default bootstrapping server is \"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
-
-::
-
-   SERVERS = http://v10.gnunet.org/hostlist [^]
-
-To use bootstrapping your configuration file should include these lines:
-
-::
-
-   [hostlist]
-   OPTIONS = -b
-   SERVERS = http://v10.gnunet.org/hostlist [^]
-
-Besides using bootstrap servers you can configure your GNUnet peer to
-receive 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 ``-e`` switch to the
-``OPTIONS`` line in the hostlist section:
-
-::
-
-   [hostlist]
-   OPTIONS = -b -e
-
-Furthermore you can specify in which file the lists are saved. To save
-the lists in the file ``hostlists.file`` just add the line:
-
-::
-
-   HOSTLISTFILE = hostlists.file
-
-Best practice is to activate both bootstrapping and hostlist learning.
-So your configuration file should include these lines:
-
-::
-
-   [hostlist]
-   OPTIONS = -b -e
-   HTTPPORT = 8080
-   SERVERS = http://v10.gnunet.org/hostlist [^]
-   HOSTLISTFILE = $SERVICEHOME/hostlists.file
-
 .. _Configuration-of-the-HOSTLIST-proxy-settings:
 
 Configuration of the HOSTLIST proxy settings
@@ -176,845 +57,6 @@ required, enter username and password in the \"Proxy username\" and
 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 ``[hostlist]`` section of the
-configuration:
-
-::
-
-   # 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 =
-
-.. _Configuring-your-peer-to-provide-a-hostlist:
-
-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.
-
-To configure your peer to act as a bootstrap server you have to add the
-``-p`` option to ``OPTIONS`` in the ``[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:
-
-::
-
-   [hostlist]
-   HTTPPORT = 12980
-   OPTIONS = -p
-
-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:
-
-::
-
-   [hostlist]
-   EXTERNAL_DNS_NAME = example.org
-   HTTPPORT = 12981
-   OPTIONS = -p -a
-
-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 ``http://example.org:12981/``.
-
-Please notice:
-
--  The hostlist is **not** human readable, so you should not try to
-   download it using your webbrowser. Just point your GNUnet peer to the
-   address!
-
--  Advertising without providing a hostlist does not make sense and will
-   not work.
-
-.. _Configuring-the-datastore:
-
-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 ``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.
-
-.. _Configuring-the-MySQL-database:
-
-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.
-
-.. _Reasons-for-using-MySQL:
-
-Reasons for using MySQL
-~~~~~~~~~~~~~~~~~~~~~~~
-
--  On up-to-date hardware where mysql can be used comfortably, this
-   module will have better performance than the other database choices
-   (according to our tests).
-
--  Its often possible to recover the mysql database from internal
-   inconsistencies. Some of the other databases do not support repair.
-
-.. _Reasons-for-not-using-MySQL:
-
-Reasons for not using MySQL
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  Memory usage (likely not an issue if you have more than 1 GB)
-
--  Complex manual setup
-
-.. _Setup-Instructions:
-
-Setup Instructions
-~~~~~~~~~~~~~~~~~~
-
--  In ``gnunet.conf`` set in section ``DATASTORE`` the value for
-   ``DATABASE`` to ``mysql``.
-
--  Access mysql as root:
-
-   .. code-block:: shell
-
-      $ mysql -u root -p
-
-   and issue the following commands, replacing ``$USER`` with the username
-   that will be running ``gnunet-arm`` (so typically \"gnunet\"):
-
-   .. code-block:: mysql
-
-      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;
-
--  In the $HOME directory of $USER, create a ``.my.cnf`` file with the
-   following lines
-
-   .. code-block:: conf
-
-      [client]
-      user=$USER
-      password=$the_password_you_like
-
-That's it. Note that ``.my.cnf`` file is a slight security risk unless
-its on a safe partition. The ``$HOME/.my.cnf`` can of course be a
-symbolic link. Luckily $USER has only privileges to mess up GNUnet's
-tables, which should be pretty harmless.
-
-.. _Testing:
-
-Testing
-~~~~~~~
-
-You should briefly try if the database connection works. First, login as
-$USER. Then use:
-
-::
-
-   $ mysql -u $USER
-   mysql> use gnunet;
-
-If you get the message
-
-::
-
-   Database changed
-
-it probably works.
-
-If you get
-
-.. code-block:: none
-
-   ERROR 2002: Can't connect to local MySQL server
-   through socket '/tmp/mysql.sock' (2)
-
-it may be resolvable by
-
-::
-
-   ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
-
-so there may be some additional trouble depending on your mysql setup.
-
-.. _Performance-Tuning:
-
-Performance Tuning
-~~~~~~~~~~~~~~~~~~
-
-For GNUnet, you probably want to set the option
-
-.. todo:: Code block not C, set appropriate language
-
-::
-
-   innodb_flush_log_at_trx_commit = 0
-
-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.
-
-.. _Setup-for-running-Testcases:
-
-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 (``make check``).
-
-.. _Configuring-the-Postgres-database:
-
-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.
-
-.. _Reasons-to-use-Postgres:
-
-Reasons to use Postgres
-~~~~~~~~~~~~~~~~~~~~~~~
-
--  Easier to setup than MySQL
-
--  Real database
-
-.. _Reasons-not-to-use-Postgres:
-
-Reasons not to use Postgres
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  Quite slow
-
--  Still some manual setup required
-
-.. _Manual-setup-instructions:
-
-Manual setup instructions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  In ``gnunet.conf`` set in section ``DATASTORE`` the value for
-   ``DATABASE`` to ``postgres``.
-
--  Access Postgres to create a user:
-
-   with Postgres 8.x, use:
-      ::
-
-         # su - postgres
-         $ createuser
-
-      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.
-
-   with Postgres 9.x, use:
-      ::
-
-         # su - postgres
-         $ createuser -d $GNUNET_USER
-
-      where $GNUNET_USER is the name of the user running GNUnet.
-
--  As that user (so typically as user \"gnunet\"), create a database (or
-   two):
-
-   ::
-
-      $ createdb gnunet
-      # this way you can run "make check"
-      $ createdb gnunetcheck
-
-Now you should be able to start ``gnunet-arm``.
-
-.. _Testing-the-setup-manually:
-
-Testing the setup manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You may want to try if the database connection works. First, again login
-as the user who will run ``gnunet-arm``. Then use:
-
-.. code-block:: psql
-
-   $ psql gnunet # or gnunetcheck
-   gnunet=> \dt
-
-If, after you have started ``gnunet-arm`` at least once, you get a
-``gn090`` table here, it probably works.
-
-.. _Configuring-the-datacache:
-
-Configuring the datacache
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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 ``QUOTA`` option in the section ``[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.
-
-.. _Configuring-the-file_002dsharing-service:
-
-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
-``START_ON_DEMAND`` option in section ``[fs]`` to \"YES\".
-Alternatively, you can run
-
-::
-
-   $ gnunet-arm -i fs
-
-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).
-
-.. _Configuring-logging:
-
-Configuring logging
-~~~~~~~~~~~~~~~~~~~
-
-Since version 0.9.0, logging in GNUnet is controlled via the ``-L`` and
-``-l`` options. Using ``-L``, a log level can be specified. With log
-level ``ERROR`` only serious errors are logged. The default log level is
-``WARNING`` which causes anything of concern to be logged. Log level
-``INFO`` can be used to log anything that might be interesting
-information whereas ``DEBUG`` can be used by developers to log debugging
-messages (but you need to run ``./configure`` with
-``--enable-logging=verbose`` to get them compiled). The ``-l`` option is
-used to specify the log file.
-
-Since most GNUnet services are managed by ``gnunet-arm``, using the
-``-l`` or ``-L`` options directly is not possible. Instead, they can be
-specified using the ``OPTIONS`` configuration value in the respective
-section for the respective service. In order to enable logging globally
-without editing the ``OPTIONS`` values for each service, ``gnunet-arm``
-supports a ``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 ``OPTIONS`` field.
-
-``GLOBAL_POSTFIX`` can contain the special sequence \"{}\" which is
-replaced by the name of the service that is being started. Furthermore,
-``GLOBAL_POSTFIX`` is special in that sequences starting with \"$\"
-anywhere in the string are expanded (according to options in ``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 ``GLOBAL_POSTFIX``. Note that specifying
-``%`` anywhere in the ``GLOBAL_POSTFIX`` disables both of these
-features.
-
-In summary, in order to get all services to log at level ``INFO`` to
-log-files called ``SERVICENAME-logs``, the following global prefix
-should be used:
-
-::
-
-   GLOBAL_POSTFIX = -l $SERVICEHOME/{}-logs -L INFO
-
-.. _Configuring-the-transport-service-and-plugins:
-
-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
-
-.. code-block:: conf
-
-   START_ON_DEMAND = 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
-
-Different are the settings for the plugins to load ``PLUGINS``. The
-first setting specifies which transport plugins to load.
-
--  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
-
-   ::
-
-      [transport-unix]
-      PORT = 22086
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
--  transport-tcp A plugin for communication with TCP. Set port to 0 for
-   client mode with outbound only connections
-
-   ::
-
-      [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
-
--  transport-udp A plugin for communication with UDP. Supports peer
-   discovery using broadcasts.
-
-   ::
-
-      [transport-udp]
-      PORT = 2086
-      BROADCAST = YES
-      BROADCAST_INTERVAL = 30 s
-      MAX_BPS = 1000000
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
--  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.
-
-   ::
-
-      [transport-http_client]
-      MAX_CONNECTIONS = 128
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
-   ::
-
-      [transport-https_client]
-      MAX_CONNECTIONS = 128
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
-   The server has a port configured and the maximum number 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 ``EXTERNAL_HOSTNAME`` setting. The webserver
-   under this address should forward the request to the peer and the
-   configure port.
-
-   ::
-
-      [transport-http_server]
-      EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
-      PORT = 1080
-      MAX_CONNECTIONS = 128
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
-   ::
-
-      [transport-https_server]
-      PORT = 4433
-      CRYPTO_INIT = NORMAL
-      KEY_FILE = https.key
-      CERT_FILE = https.cert
-      MAX_CONNECTIONS = 128
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
--  transport-wlan
-
-   The next section describes how to setup the WLAN plugin, so here only
-   the settings. Just specify the interface to use:
-
-   ::
-
-      [transport-wlan]
-      # Name of the interface in monitor mode (typically monX)
-      INTERFACE = mon0
-      # Real hardware, no testing
-      TESTMODE = 0
-      TESTING_IGNORE_KEYS = ACCEPT_FROM;
-
-.. _Configuring-the-WLAN-transport-plugin:
-
-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.
-
-.. _Requirements-for-the-WLAN-plugin:
-
-Requirements for the WLAN plugin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
--  wlan network card with monitor support and packet injection (see
-   `aircrack-ng.org <http://www.aircrack-ng.org/>`__)
-
--  Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
-   2.6.35 and 2.6.38
-
--  Wlantools to create the a monitor interface, tested with airmon-ng of
-   the aircrack-ng package
-
-.. _Configuration:
-
-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)
-
-::
-
-   # 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
-
-.. _Before-starting-GNUnet:
-
-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:
-
-::
-
-   sudo airmon-ng start wlan0
-
-Here is an example what the result should look like:
-
-::
-
-   Interface Chipset Driver
-   wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
-   (monitor mode enabled on mon0)
-
-The monitor interface is mon0 is the one that you have to put into the
-configuration file.
-
-.. _Limitations-and-known-bugs:
-
-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, e.g. by using:
-
-::
-
-   iwconfig wlan0 channel 1
-
-.. _Configuring-HTTP_0028S_0029-reverse-proxy-functionality-using-Apache-or-nginx:
-
-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
-website this improves censorship resistance since it looks as normal
-surfing behaviour.
-
-To do so, you have to do two things:
-
--  Configure your webserver to forward the GNUnet HTTP traffic
-
--  Configure your GNUnet peer to announce the respective address
-
-As an example we want to use GNUnet peer running:
-
--  HTTP server plugin on ``gnunet.foo.org:1080``
-
--  HTTPS server plugin on ``gnunet.foo.org:4433``
-
--  A apache or nginx webserver on
-   `http://www.foo.org:80/ <http://www.foo.org/>`__
-
--  A apache or nginx webserver on https://www.foo.org:443/
-
-And we want the webserver to accept GNUnet traffic under
-``http://www.foo.org/bar/``. The required steps are described here:
-
-.. _Reverse-Proxy-_002d-Configure-your-Apache2-HTTP-webserver:
-
-Reverse Proxy - Configure your Apache2 HTTP webserver
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-First of all you need mod_proxy installed.
-
-Edit your webserver configuration. Edit ``/etc/apache2/apache2.conf`` or
-the site-specific configuration file.
-
-In the respective ``server config``,\ ``virtual host`` or ``directory``
-section add the following lines:
-
-::
-
-   ProxyTimeout 300
-   ProxyRequests Off
-   <Location /bar/ >
-   ProxyPass http://gnunet.foo.org:1080/
-   ProxyPassReverse http://gnunet.foo.org:1080/
-   </Location>
-
-.. _Reverse-Proxy-_002d-Configure-your-Apache2-HTTPS-webserver:
-
-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
-``apache2/sites-available/default-ssl``.
-
-In the respective HTTPS ``server config``,\ ``virtual host`` or
-``directory`` section add the following lines:
-
-::
-
-   SSLProxyEngine On
-   ProxyTimeout 300
-   ProxyRequests Off
-   <Location /bar/ >
-   ProxyPass https://gnunet.foo.org:4433/
-   ProxyPassReverse https://gnunet.foo.org:4433/
-   </Location>
-
-More information about the apache mod_proxy configuration can be found
-in the `Apache
-documentation <http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass>`__.
-
-.. _Reverse-Proxy-_002d-Configure-your-nginx-HTTPS-webserver:
-
-Reverse Proxy - Configure your nginx HTTPS webserver
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Since nginx does not support chunked encoding, you first of all have to
-install the ``chunkin``
-`module <http://wiki.nginx.org/HttpChunkinModule>`__.
-
-To enable chunkin add:
-
-.. code-block:: nginx
-
-   chunkin on;
-   error_page 411 = @my_411_error;
-   location @my_411_error {
-   chunkin_resume;
-   }
-
-Edit your webserver configuration. Edit ``/etc/nginx/nginx.conf`` or the
-site-specific configuration file.
-
-In the ``server`` section add:
-
-.. code-block:: nginx
-
-   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;
-   }
-
-.. _Reverse-Proxy-_002d-Configure-your-nginx-HTTP-webserver:
-
-Reverse Proxy - Configure your nginx HTTP webserver
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Edit your webserver configuration. Edit ``/etc/nginx/nginx.conf`` or the
-site-specific configuration file.
-
-In the ``server`` section add:
-
-.. code-block:: nginx
-
-   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;
-   }
-
-.. _Reverse-Proxy-_002d-Configure-your-GNUnet-peer:
-
-Reverse Proxy - Configure your GNUnet peer
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To have your GNUnet peer announce the address, you have to specify the
-``EXTERNAL_HOSTNAME`` option in the ``[transport-http_server]`` section:
-
-::
-
-   [transport-http_server]
-   EXTERNAL_HOSTNAME = http://www.foo.org/bar/
-
-and/or ``[transport-https_server]`` section:
-
-::
-
-   [transport-https_server]
-   EXTERNAL_HOSTNAME = https://www.foo.org/bar/
-
-Now restart your webserver and your peer\...
-
-.. _Blacklisting-peers:
-
-Blacklisting peers
-~~~~~~~~~~~~~~~~~~
-
-Transport service supports to deny connecting to a specific peer of to a
-specific peer with a specific transport plugin using the 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:
-
-.. todo:: too long?
-.. todo:: verify whether these still produce errors in pdf output
-
-::
-
-   [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
-   P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
-
-To blacklist connections to P565\... on peer AG2P\... using all plugins
-add:
-
-::
-
-   [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
-   P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
-
-You can also add a blacklist client using 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)
-
--  Do we have a local blacklist entry for this peer and this plugin?
-
--  YES: disallow connection
-
--  Do we have a local blacklist entry for this peer and all plugins?
-
--  YES: disallow connection
-
--  Does one of the clients disallow?
-
--  YES: disallow connection
-
 .. _Configuration-of-the-HTTP-and-HTTPS-transport-plugins:
 
 Configuration of the HTTP and HTTPS transport plugins
@@ -1042,521 +84,3 @@ can select the appropriate proxy type. The hostname or IP address
 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 ``[transport-http_client]`` and
-``[transport-https_client]`` section of the configuration:
-
-::
-
-   # 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 =
-
-.. _Configuring-the-GNU-Name-System:
-
-Configuring the GNU Name System
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. _Configuring-system_002dwide-DNS-interception:
-
-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
-``gnunet-service-arm`` as user and group 'gnunet'. You also need to be
-sure to run ``make install`` as root (or use the ``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 ``gnunet-service-dns`` will then start helper programs that will
-make the necessary changes to your firewall (``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:
-
--  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 ``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
-   ``gnunet-gns-proxy`` and inform your browser to use the Socks5 proxy
-   which ``gnunet-gns-proxy`` makes available by default on port 7777.
-
--  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.
-
--  Use a W32 resolver plugin (recommended on W32) This is currently the
-   only option on W32 systems.
-
--  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).
-
-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.
-
-.. _Configuring-the-GNS-nsswitch-plugin:
-
-Configuring the GNS nsswitch plugin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The Name Service Switch (NSS) is a facility in Unix-like operating
-systems (in most cases provided by 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
-``/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
-
--  install GNUnet as root or
-
--  compile GNUnet with the ``--with-sudo=yes`` switch.
-
-Name resolution is controlled by the *hosts* section in the NSS
-configuration. By default this section first performs a lookup in the
-``/etc/hosts`` file and then in DNS. The nsswitch file should contain a
-line similar to:
-
-::
-
-   hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4
-
-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 ``/etc/nsswitch.conf`` file before DNS related
-plugins:
-
-::
-
-   ...
-   hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4
-   ...
-
-The ``NOTFOUND=return`` will ensure that if a ``.gnu`` name is not found
-in GNS it will not be queried in DNS.
-
-.. _GNS-Proxy-Setup:
-
-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:
-
--  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 ``Host: example.com`` header in the
-   request from your browser. However, your browser might be using
-   ``example.gnu`` for the ``Host`` header and might only accept (and
-   send) cookies for ``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).
-
--  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 ``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.
-
--  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)
-
-.. _Setup-of-the-GNS-CA:
-
-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:
-
-::
-
-   $ gnunet-gns-proxy-setup-ca
-
-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 ``*.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 **not** work with libcurl
-compiled against OpenSSL.
-
-You can check the configuration your libcurl was build with by running:
-
-::
-
-   curl --version
-
-the output will look like this (without the linebreaks):
-
-::
-
-   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
-
-.. _Testing-the-GNS-setup:
-
-Testing the GNS setup
-^^^^^^^^^^^^^^^^^^^^^
-
-Now for testing purposes we can create some records in our zone to test
-the SSL functionality of the proxy:
-
-::
-
-   $ 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
-
-At this point we can start the proxy. Simply execute
-
-::
-
-   $ gnunet-arm -i gns-proxy
-
-To run the proxy at all times in the future, you should change your
-configuration as follows:
-
-::
-
-   $ gnunet-config -s gns-proxy -o AUTOSTART -V YES
-
-Configure your browser to use this SOCKSv5 proxy using ``localhost`` on
-port 7777. If you use ``Firefox`` (or one of its derivatives/forks such
-as Icecat) you also have to go to ``about:config`` and set the key
-``network.proxy.socks_remote_dns`` to ``true``.
-
-When you visit ``https://homepage.test/``, you should get to the
-``https://gnunet.org/`` frontpage and the browser (with the correctly
-configured proxy) should give you a valid SSL certificate for
-``homepage.gnu`` and no warnings. It should look like this:
-
-.. todo:: Image missing, does it no longer exist?
-
-.. _Migrating-existing-DNS-zones-into-GNS:
-
-Migrating existing DNS zones into GNS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To migrate an existing zone into GNS use the Ascension tool.
-
-Ascension transfers entire zones into GNS by doing incremental zone
-transfers and then adding the records to GNS.
-
-Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR
-depending on whether or not there exists a SOA record for the zone. If
-that is the case it will take the serial as a reference point and
-request the zone. The server will either answer the IXFR request with a
-correct incremental zone or with the entire zone, which depends on the
-server configuration.
-
-You can find the source code here:
-``https://git.gnunet.org/ascension.git/``
-
-The software can be installed into a Python virtual environment like
-this:
-
-::
-
-   $ python3 -m venv .venv
-   $ source .venv/bin/activate
-   $ python3 setup.py install
-
-Or installed globally like this:
-
-::
-
-   $ sudo python3 setup.py install
-
-Pip will then install all the necessary requirements that are needed to
-run Ascension. For development purposes a virtual environment should
-suffice. Keeping a virtual environment helps with keeping things tidy
-and prevents breaking of Ascension through a future Python update.
-
-The advantage of using a virtual environment is, that all the
-dependencies can be installed separately in different versions without
-touching your systems Python installation and its dependencies.
-
-Another way to install Ascension on Debian is to install the
-python3-ascension package. It can be found within the above mentioned
-Ascension git repository. This also adds a system user called ascension
-and runs a GNUnet peer in the background. Please note: This only works
-if a recent version of GNUnet is installed on your system. The version
-number of Ascension is chosen according to the required feature level of
-GNUnet: Ascension 0.11.5 is only compatible with GNUnet 0.11.5 or later
-and so on. As Debian's packages for GNUnet are outdated even in
-experimental, you will need to install GNUnet manually See `Installing
-GNUnet <#Installing-GNUnet>`__.
-
-Please check See `Migrating an existing DNS zone into
-GNS <#Migrating-an-existing-DNS-zone-into-GNS>`__, for usage manual of
-the tool.
-
-.. _Configuring-the-GNUnet-VPN:
-
-Configuring the GNUnet VPN
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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. see `Configuring the GNU Name
-System <#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:
-
-.. _IPv4-address-for-interface:
-
-IPv4 address for interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is the IPv4 address the VPN interface will get. You should pick a
-'private' IPv4 network that is not yet in use for you system. For
-example, if you use ``10.0.0.1/255.255.0.0`` already, you might use
-``10.1.0.1/255.255.0.0``. If you use ``10.0.0.1/255.0.0.0`` already,
-then you might use ``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 (``255.255.0.0`` or, even
-better, ``255.0.0.0``) to allow more mappings of remote IP Addresses
-into this range. However, even a ``255.255.255.0`` mask will suffice for
-most users.
-
-.. _IPv6-address-for-interface:
-
-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 ``fe80:``). A
-subnet Unique Local Unicast (``fd00::/8`` prefix) that you are currently
-not using would be a good choice.
-
-.. _Configuring-the-GNUnet-VPN-DNS:
-
-Configuring the GNUnet VPN DNS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To resolve names for remote nodes, activate the DNS exit option.
-
-.. _Configuring-the-GNUnet-VPN-Exit-Service:
-
-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 do other mischiefs 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 (e.g. 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:
-
-.. _IP-Address-of-external-DNS-resolver:
-
-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.
-
-.. _IPv4-address-for-Exit-interface:
-
-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.
-
-.. _IPv6-address-for-Exit-interface:
-
-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 ``2001:4ca0::1234/64``, then using
-``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 (``2001:4ca0::1:0/112`` for example) through your computer
-(this should be automatic with IPv6, but obviously anything can be
-disabled).
-
-.. _Bandwidth-Configuration:
-
-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.
-
-.. _Configuring-NAT:
-
-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\" privileges 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.
-
-.. _Peer-configuration-for-distributors-_0028e_002eg_002e-Operating-Systems_0029:
-
-Peer configuration for distributors (e.g. Operating Systems)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The \"GNUNET_DATA_HOME\" in \"[PATHS]\" in ``/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, distributors may consider pointing
-\"GNUNET_RUNTIME_DIR\" to \"/var/run/gnunet/\" and \"GNUNET_HOME\" to
-\"/var/lib/gnunet/\". Also, should a distributor decide to override
-system defaults, all of these changes should be done in a custom
-``/etc/gnunet.conf`` and not in the files in the ``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\".
-Distributors might want to include a wrapper for gnunet-setup that
-allows the desktop-user to \"sudo\" (e.g. using gtksudo) to the
-\"gnunet\" user account and then runs \"gnunet-arm -e\",
-\"gnunet-setup\" and \"gnunet-arm -s\" in sequence.
diff --git a/guis/index.rst b/guis/index.rst
@@ -4,3 +4,4 @@ GUIs
 .. toctree::
 
    gtk
+   fs-gtk
diff --git a/man_users/configuration.rst b/man_users/configuration.rst
@@ -0,0 +1,1226 @@
+Advanced Configuration
+----------------------
+
+.. _Configuring-the-Friend_002dto_002dFriend-_0028F2F_0029-mode:
+
+Configuring the Friend-to-Friend (F2F) mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+GNUnet knows three basic modes of operation:
+
+-  In standard \"peer-to-peer\" mode, your peer will connect to any
+   peer.
+
+-  In the pure \"friend-to-friend\" mode, your peer will ONLY connect to
+   peers from a list of friends specified in the configuration.
+
+-  Finally, in mixed mode, GNUnet will only connect to arbitrary peers
+   if it has at least a specified number of connections to friends.
+
+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
+
+::
+
+   $ gnunet-peerinfo -sq
+
+The resulting output of this command needs to be added to your
+``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 ``friends`` file in the
+``FRIENDS`` option of the \"topology\" section.
+
+Once you have created the ``friends`` file, you can tell GNUnet to only
+connect to your friends by setting the ``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
+``MINIMUM-FRIENDS`` to zero and ``FRIENDS_ONLY`` to NO. This is the
+default.
+
+.. _Configuring-the-hostlist-to-bootstrap:
+
+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 ``[hostlist]``-section in your
+configuration file. You have to set the argument ``-b`` in the options
+line:
+
+::
+
+   [hostlist]
+   OPTIONS = -b
+
+Additionally you have to specify which server you want to use. The
+default bootstrapping server is \"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
+
+::
+
+   SERVERS = http://v10.gnunet.org/hostlist [^]
+
+To use bootstrapping your configuration file should include these lines:
+
+::
+
+   [hostlist]
+   OPTIONS = -b
+   SERVERS = http://v10.gnunet.org/hostlist [^]
+
+Besides using bootstrap servers you can configure your GNUnet peer to
+receive 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 ``-e`` switch to the
+``OPTIONS`` line in the hostlist section:
+
+::
+
+   [hostlist]
+   OPTIONS = -b -e
+
+Furthermore you can specify in which file the lists are saved. To save
+the lists in the file ``hostlists.file`` just add the line:
+
+::
+
+   HOSTLISTFILE = hostlists.file
+
+Best practice is to activate both bootstrapping and hostlist learning.
+So your configuration file should include these lines:
+
+::
+
+   [hostlist]
+   OPTIONS = -b -e
+   HTTPPORT = 8080
+   SERVERS = http://v10.gnunet.org/hostlist [^]
+   HOSTLISTFILE = $SERVICEHOME/hostlists.file
+
+.. _Configuration-of-the-HOSTLIST-proxy-settings-cli:
+
+Configuration of the HOSTLIST proxy settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The hostlist client can be configured to use a proxy to connect to the
+hostlist server.
+
+The hostlist client supports the following proxy types at the moment:
+
+-  HTTP and HTTP 1.0 only proxy
+
+-  SOCKS 4/4a/5/5 with hostname
+
+In addition authentication at the proxy with username and password can
+be configured.
+
+To provide these options directly in the configuration, you can enter
+the following settings in the ``[hostlist]`` section of the
+configuration:
+
+::
+
+   # 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 =
+
+.. _Configuring-your-peer-to-provide-a-hostlist:
+
+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.
+
+To configure your peer to act as a bootstrap server you have to add the
+``-p`` option to ``OPTIONS`` in the ``[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:
+
+::
+
+   [hostlist]
+   HTTPPORT = 12980
+   OPTIONS = -p
+
+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:
+
+::
+
+   [hostlist]
+   EXTERNAL_DNS_NAME = example.org
+   HTTPPORT = 12981
+   OPTIONS = -p -a
+
+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 ``http://example.org:12981/``.
+
+Please notice:
+
+-  The hostlist is **not** human readable, so you should not try to
+   download it using your webbrowser. Just point your GNUnet peer to the
+   address!
+
+-  Advertising without providing a hostlist does not make sense and will
+   not work.
+
+.. _Configuring-the-datastore:
+
+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 ``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.
+
+.. _Configuring-the-MySQL-database:
+
+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.
+
+.. _Reasons-for-using-MySQL:
+
+Reasons for using MySQL
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  On up-to-date hardware where mysql can be used comfortably, this
+   module will have better performance than the other database choices
+   (according to our tests).
+
+-  Its often possible to recover the mysql database from internal
+   inconsistencies. Some of the other databases do not support repair.
+
+.. _Reasons-for-not-using-MySQL:
+
+Reasons for not using MySQL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Memory usage (likely not an issue if you have more than 1 GB)
+
+-  Complex manual setup
+
+.. _Setup-Instructions:
+
+Setup Instructions
+~~~~~~~~~~~~~~~~~~
+
+-  In ``gnunet.conf`` set in section ``DATASTORE`` the value for
+   ``DATABASE`` to ``mysql``.
+
+-  Access mysql as root:
+
+   .. code-block:: shell
+
+      $ mysql -u root -p
+
+   and issue the following commands, replacing ``$USER`` with the username
+   that will be running ``gnunet-arm`` (so typically \"gnunet\"):
+
+   .. code-block:: mysql
+
+      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;
+
+-  In the $HOME directory of $USER, create a ``.my.cnf`` file with the
+   following lines
+
+   .. code-block:: conf
+
+      [client]
+      user=$USER
+      password=$the_password_you_like
+
+That's it. Note that ``.my.cnf`` file is a slight security risk unless
+its on a safe partition. The ``$HOME/.my.cnf`` can of course be a
+symbolic link. Luckily $USER has only privileges to mess up GNUnet's
+tables, which should be pretty harmless.
+
+.. _Testing:
+
+Testing
+~~~~~~~
+
+You should briefly try if the database connection works. First, login as
+$USER. Then use:
+
+::
+
+   $ mysql -u $USER
+   mysql> use gnunet;
+
+If you get the message
+
+::
+
+   Database changed
+
+it probably works.
+
+If you get
+
+.. code-block:: none
+
+   ERROR 2002: Can't connect to local MySQL server
+   through socket '/tmp/mysql.sock' (2)
+
+it may be resolvable by
+
+::
+
+   ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock
+
+so there may be some additional trouble depending on your mysql setup.
+
+.. _Performance-Tuning:
+
+Performance Tuning
+~~~~~~~~~~~~~~~~~~
+
+For GNUnet, you probably want to set the option
+
+.. todo:: Code block not C, set appropriate language
+
+::
+
+   innodb_flush_log_at_trx_commit = 0
+
+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.
+
+.. _Setup-for-running-Testcases:
+
+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 (``make check``).
+
+.. _Configuring-the-Postgres-database:
+
+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.
+
+.. _Reasons-to-use-Postgres:
+
+Reasons to use Postgres
+~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Easier to setup than MySQL
+
+-  Real database
+
+.. _Reasons-not-to-use-Postgres:
+
+Reasons not to use Postgres
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  Quite slow
+
+-  Still some manual setup required
+
+.. _Manual-setup-instructions:
+
+Manual setup instructions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  In ``gnunet.conf`` set in section ``DATASTORE`` the value for
+   ``DATABASE`` to ``postgres``.
+
+-  Access Postgres to create a user:
+
+   with Postgres 8.x, use:
+      ::
+
+         # su - postgres
+         $ createuser
+
+      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.
+
+   with Postgres 9.x, use:
+      ::
+
+         # su - postgres
+         $ createuser -d $GNUNET_USER
+
+      where $GNUNET_USER is the name of the user running GNUnet.
+
+-  As that user (so typically as user \"gnunet\"), create a database (or
+   two):
+
+   ::
+
+      $ createdb gnunet
+      # this way you can run "make check"
+      $ createdb gnunetcheck
+
+Now you should be able to start ``gnunet-arm``.
+
+.. _Testing-the-setup-manually:
+
+Testing the setup manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may want to try if the database connection works. First, again login
+as the user who will run ``gnunet-arm``. Then use:
+
+.. code-block:: psql
+
+   $ psql gnunet # or gnunetcheck
+   gnunet=> \dt
+
+If, after you have started ``gnunet-arm`` at least once, you get a
+``gn090`` table here, it probably works.
+
+.. _Configuring-the-datacache:
+
+Configuring the datacache
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 ``QUOTA`` option in the section ``[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.
+
+.. _Configuring-the-file_002dsharing-service:
+
+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
+``START_ON_DEMAND`` option in section ``[fs]`` to \"YES\".
+Alternatively, you can run
+
+::
+
+   $ gnunet-arm -i fs
+
+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).
+
+.. _Configuring-logging:
+
+Configuring logging
+~~~~~~~~~~~~~~~~~~~
+
+Since version 0.9.0, logging in GNUnet is controlled via the ``-L`` and
+``-l`` options. Using ``-L``, a log level can be specified. With log
+level ``ERROR`` only serious errors are logged. The default log level is
+``WARNING`` which causes anything of concern to be logged. Log level
+``INFO`` can be used to log anything that might be interesting
+information whereas ``DEBUG`` can be used by developers to log debugging
+messages (but you need to run ``./configure`` with
+``--enable-logging=verbose`` to get them compiled). The ``-l`` option is
+used to specify the log file.
+
+Since most GNUnet services are managed by ``gnunet-arm``, using the
+``-l`` or ``-L`` options directly is not possible. Instead, they can be
+specified using the ``OPTIONS`` configuration value in the respective
+section for the respective service. In order to enable logging globally
+without editing the ``OPTIONS`` values for each service, ``gnunet-arm``
+supports a ``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 ``OPTIONS`` field.
+
+``GLOBAL_POSTFIX`` can contain the special sequence \"{}\" which is
+replaced by the name of the service that is being started. Furthermore,
+``GLOBAL_POSTFIX`` is special in that sequences starting with \"$\"
+anywhere in the string are expanded (according to options in ``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 ``GLOBAL_POSTFIX``. Note that specifying
+``%`` anywhere in the ``GLOBAL_POSTFIX`` disables both of these
+features.
+
+In summary, in order to get all services to log at level ``INFO`` to
+log-files called ``SERVICENAME-logs``, the following global prefix
+should be used:
+
+::
+
+   GLOBAL_POSTFIX = -l $SERVICEHOME/{}-logs -L INFO
+
+.. _Configuring-the-transport-service-and-plugins:
+
+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
+
+.. code-block:: conf
+
+   START_ON_DEMAND = 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
+
+Different are the settings for the plugins to load ``PLUGINS``. The
+first setting specifies which transport plugins to load.
+
+-  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
+
+   ::
+
+      [transport-unix]
+      PORT = 22086
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+-  transport-tcp A plugin for communication with TCP. Set port to 0 for
+   client mode with outbound only connections
+
+   ::
+
+      [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
+
+-  transport-udp A plugin for communication with UDP. Supports peer
+   discovery using broadcasts.
+
+   ::
+
+      [transport-udp]
+      PORT = 2086
+      BROADCAST = YES
+      BROADCAST_INTERVAL = 30 s
+      MAX_BPS = 1000000
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+-  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.
+
+   ::
+
+      [transport-http_client]
+      MAX_CONNECTIONS = 128
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+   ::
+
+      [transport-https_client]
+      MAX_CONNECTIONS = 128
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+   The server has a port configured and the maximum number 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 ``EXTERNAL_HOSTNAME`` setting. The webserver
+   under this address should forward the request to the peer and the
+   configure port.
+
+   ::
+
+      [transport-http_server]
+      EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet
+      PORT = 1080
+      MAX_CONNECTIONS = 128
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+   ::
+
+      [transport-https_server]
+      PORT = 4433
+      CRYPTO_INIT = NORMAL
+      KEY_FILE = https.key
+      CERT_FILE = https.cert
+      MAX_CONNECTIONS = 128
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+-  transport-wlan
+
+   The next section describes how to setup the WLAN plugin, so here only
+   the settings. Just specify the interface to use:
+
+   ::
+
+      [transport-wlan]
+      # Name of the interface in monitor mode (typically monX)
+      INTERFACE = mon0
+      # Real hardware, no testing
+      TESTMODE = 0
+      TESTING_IGNORE_KEYS = ACCEPT_FROM;
+
+.. _Configuring-the-WLAN-transport-plugin:
+
+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.
+
+.. _Requirements-for-the-WLAN-plugin:
+
+Requirements for the WLAN plugin
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+-  wlan network card with monitor support and packet injection (see
+   `aircrack-ng.org <http://www.aircrack-ng.org/>`__)
+
+-  Linux kernel with mac80211 stack, introduced in 2.6.22, tested with
+   2.6.35 and 2.6.38
+
+-  Wlantools to create the a monitor interface, tested with airmon-ng of
+   the aircrack-ng package
+
+.. _Configuration:
+
+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)
+
+::
+
+   # 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
+
+.. _Before-starting-GNUnet:
+
+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:
+
+::
+
+   sudo airmon-ng start wlan0
+
+Here is an example what the result should look like:
+
+::
+
+   Interface Chipset Driver
+   wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0]
+   (monitor mode enabled on mon0)
+
+The monitor interface is mon0 is the one that you have to put into the
+configuration file.
+
+.. _Limitations-and-known-bugs:
+
+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, e.g. by using:
+
+::
+
+   iwconfig wlan0 channel 1
+
+.. _Configuring-HTTP_0028S_0029-reverse-proxy-functionality-using-Apache-or-nginx:
+
+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
+website this improves censorship resistance since it looks as normal
+surfing behaviour.
+
+To do so, you have to do two things:
+
+-  Configure your webserver to forward the GNUnet HTTP traffic
+
+-  Configure your GNUnet peer to announce the respective address
+
+As an example we want to use GNUnet peer running:
+
+-  HTTP server plugin on ``gnunet.foo.org:1080``
+
+-  HTTPS server plugin on ``gnunet.foo.org:4433``
+
+-  A apache or nginx webserver on
+   `http://www.foo.org:80/ <http://www.foo.org/>`__
+
+-  A apache or nginx webserver on https://www.foo.org:443/
+
+And we want the webserver to accept GNUnet traffic under
+``http://www.foo.org/bar/``. The required steps are described here:
+
+.. _Reverse-Proxy-_002d-Configure-your-Apache2-HTTP-webserver:
+
+Reverse Proxy - Configure your Apache2 HTTP webserver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First of all you need mod_proxy installed.
+
+Edit your webserver configuration. Edit ``/etc/apache2/apache2.conf`` or
+the site-specific configuration file.
+
+In the respective ``server config``,\ ``virtual host`` or ``directory``
+section add the following lines:
+
+::
+
+   ProxyTimeout 300
+   ProxyRequests Off
+   <Location /bar/ >
+   ProxyPass http://gnunet.foo.org:1080/
+   ProxyPassReverse http://gnunet.foo.org:1080/
+   </Location>
+
+.. _Reverse-Proxy-_002d-Configure-your-Apache2-HTTPS-webserver:
+
+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
+``apache2/sites-available/default-ssl``.
+
+In the respective HTTPS ``server config``,\ ``virtual host`` or
+``directory`` section add the following lines:
+
+::
+
+   SSLProxyEngine On
+   ProxyTimeout 300
+   ProxyRequests Off
+   <Location /bar/ >
+   ProxyPass https://gnunet.foo.org:4433/
+   ProxyPassReverse https://gnunet.foo.org:4433/
+   </Location>
+
+More information about the apache mod_proxy configuration can be found
+in the `Apache
+documentation <http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass>`__.
+
+.. _Reverse-Proxy-_002d-Configure-your-nginx-HTTPS-webserver:
+
+Reverse Proxy - Configure your nginx HTTPS webserver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since nginx does not support chunked encoding, you first of all have to
+install the ``chunkin``
+`module <http://wiki.nginx.org/HttpChunkinModule>`__.
+
+To enable chunkin add:
+
+.. code-block:: nginx
+
+   chunkin on;
+   error_page 411 = @my_411_error;
+   location @my_411_error {
+   chunkin_resume;
+   }
+
+Edit your webserver configuration. Edit ``/etc/nginx/nginx.conf`` or the
+site-specific configuration file.
+
+In the ``server`` section add:
+
+.. code-block:: nginx
+
+   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;
+   }
+
+.. _Reverse-Proxy-_002d-Configure-your-nginx-HTTP-webserver:
+
+Reverse Proxy - Configure your nginx HTTP webserver
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Edit your webserver configuration. Edit ``/etc/nginx/nginx.conf`` or the
+site-specific configuration file.
+
+In the ``server`` section add:
+
+.. code-block:: nginx
+
+   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;
+   }
+
+.. _Reverse-Proxy-_002d-Configure-your-GNUnet-peer:
+
+Reverse Proxy - Configure your GNUnet peer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To have your GNUnet peer announce the address, you have to specify the
+``EXTERNAL_HOSTNAME`` option in the ``[transport-http_server]`` section:
+
+::
+
+   [transport-http_server]
+   EXTERNAL_HOSTNAME = http://www.foo.org/bar/
+
+and/or ``[transport-https_server]`` section:
+
+::
+
+   [transport-https_server]
+   EXTERNAL_HOSTNAME = https://www.foo.org/bar/
+
+Now restart your webserver and your peer\...
+
+.. _Blacklisting-peers:
+
+Blacklisting peers
+~~~~~~~~~~~~~~~~~~
+
+Transport service supports to deny connecting to a specific peer of to a
+specific peer with a specific transport plugin using the 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:
+
+.. todo:: too long?
+.. todo:: verify whether these still produce errors in pdf output
+
+::
+
+   [transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
+   P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp
+
+To blacklist connections to P565\... on peer AG2P\... using all plugins
+add:
+
+::
+
+   [transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]
+   P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =
+
+You can also add a blacklist client using 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)
+
+-  Do we have a local blacklist entry for this peer and this plugin?
+
+-  YES: disallow connection
+
+-  Do we have a local blacklist entry for this peer and all plugins?
+
+-  YES: disallow connection
+
+-  Does one of the clients disallow?
+
+-  YES: disallow connection
+
+.. _Configuration-of-the-HTTP-and-HTTPS-transport-plugins-cli:
+
+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.
+
+Both the HTTP and HTTPS clients support the following proxy types at the
+moment:
+
+-  HTTP 1.1 proxy
+
+-  SOCKS 4/4a/5/5 with hostname
+
+In addition authentication at the proxy with username and password can
+be configured.
+
+To configure these options directly in the configuration, you can
+configure the following settings in the ``[transport-http_client]`` and
+``[transport-https_client]`` section of the configuration:
+
+::
+
+   # 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 =
+
+.. _Configuring-the-GNUnet-VPN:
+
+Configuring the GNUnet VPN
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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. see `Configuring the GNU Name
+System <#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:
+
+.. _IPv4-address-for-interface:
+
+IPv4 address for interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is the IPv4 address the VPN interface will get. You should pick a
+'private' IPv4 network that is not yet in use for you system. For
+example, if you use ``10.0.0.1/255.255.0.0`` already, you might use
+``10.1.0.1/255.255.0.0``. If you use ``10.0.0.1/255.0.0.0`` already,
+then you might use ``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 (``255.255.0.0`` or, even
+better, ``255.0.0.0``) to allow more mappings of remote IP Addresses
+into this range. However, even a ``255.255.255.0`` mask will suffice for
+most users.
+
+.. _IPv6-address-for-interface:
+
+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 ``fe80:``). A
+subnet Unique Local Unicast (``fd00::/8`` prefix) that you are currently
+not using would be a good choice.
+
+.. _Configuring-the-GNUnet-VPN-DNS:
+
+Configuring the GNUnet VPN DNS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To resolve names for remote nodes, activate the DNS exit option.
+
+.. _Configuring-the-GNUnet-VPN-Exit-Service:
+
+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 do other mischiefs 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 (e.g. 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:
+
+.. _IP-Address-of-external-DNS-resolver:
+
+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.
+
+.. _IPv4-address-for-Exit-interface:
+
+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.
+
+.. _IPv6-address-for-Exit-interface:
+
+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 ``2001:4ca0::1234/64``, then using
+``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 (``2001:4ca0::1:0/112`` for example) through your computer
+(this should be automatic with IPv6, but obviously anything can be
+disabled).
+
+.. _Bandwidth-Configuration:
+
+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.
+
+.. _Configuring-NAT:
+
+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\" privileges 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.
+
+.. _Peer-configuration-for-distributors-_0028e_002eg_002e-Operating-Systems_0029:
+
+Peer configuration for distributors (e.g. Operating Systems)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The \"GNUNET_DATA_HOME\" in \"[PATHS]\" in ``/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, distributors may consider pointing
+\"GNUNET_RUNTIME_DIR\" to \"/var/run/gnunet/\" and \"GNUNET_HOME\" to
+\"/var/lib/gnunet/\". Also, should a distributor decide to override
+system defaults, all of these changes should be done in a custom
+``/etc/gnunet.conf`` and not in the files in the ``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\".
+Distributors might want to include a wrapper for gnunet-setup that
+allows the desktop-user to \"sudo\" (e.g. using gtksudo) to the
+\"gnunet\" user account and then runs \"gnunet-arm -e\",
+\"gnunet-setup\" and \"gnunet-arm -s\" in sequence.
diff --git a/man_users/fs.rst b/man_users/fs.rst
@@ -167,6 +167,8 @@ better chance of denying knowledge of the existence of the file, even if
 it is still (encrypted) on the drive and the adversary is able to crack
 the encryption (e.g. by guessing the keyword).
 
+.. _fs_002dConcepts:
+
 Concepts
 ~~~~~~~~
 
@@ -182,4 +184,286 @@ updates to certain content to be made available. This section is
 supposed to introduce users to the concepts that are used to achieve
 these goals.
 
-TODO concepts. Should they be here?
+.. _Files:
+
+Files
+^^^^^
+
+A file in GNUnet is just a sequence of bytes. Any file-format is allowed
+and the maximum file size is theoretically :math:`2^64 - 1` bytes,
+except that it would take an impractical amount of time to share such a
+file. GNUnet itself never interprets the contents of shared files,
+except when using GNU libextractor to obtain keywords.
+
+.. _Keywords:
+
+Keywords
+^^^^^^^^
+
+Keywords are the most simple mechanism to find files on GNUnet. Keywords
+are **case-sensitive** and the search string must always match
+**exactly** the keyword used by the person providing the file. Keywords
+are never transmitted in plaintext. The only way for an adversary to
+determine the keyword that you used to search is to guess it (which then
+allows the adversary to produce the same search request). Since
+providing keywords by hand for each shared file is tedious, GNUnet uses
+GNU libextractor to help automate this process. Starting a keyword
+search on a slow machine can take a little while since the keyword
+search involves computing a fresh RSA key to formulate the request.
+
+.. _Directories:
+
+Directories
+^^^^^^^^^^^
+
+A directory in GNUnet is a list of file identifiers with meta data. The
+file identifiers provide sufficient information about the files to allow
+downloading the contents. Once a directory has been created, it cannot
+be changed since it is treated just like an ordinary file by the
+network. Small files (of a few kilobytes) can be inlined in the
+directory, so that a separate download becomes unnecessary.
+
+Directories are shared just like ordinary files. If you download a
+directory with ``gnunet-download``, you can use ``gnunet-directory`` to
+list its contents. The canonical extension for GNUnet directories when
+stored as files in your local file-system is \".gnd\". The contents of a
+directory are URIs and meta data. The URIs contain all the information
+required by ``gnunet-download`` to retrieve the file. The meta data
+typically includes the mime-type, description, a filename and other meta
+information, and possibly even the full original file (if it was small).
+
+.. _Egos-and-File_002dSharing:
+
+Egos and File-Sharing
+^^^^^^^^^^^^^^^^^^^^^
+
+When sharing files, it is sometimes desirable to build a reputation as a
+source for quality information. With egos, publishers can
+(cryptographically) sign files, thereby demonstrating that various files
+were published by the same entity. An ego thus allows users to link
+different publication events, thereby deliberately reducing anonymity to
+pseudonymity.
+
+Egos used in GNUnet's file-sharing for such pseudonymous publishing also
+correspond to the egos used to identify and sign zones in the GNU Name
+System. However, if the same ego is used for file-sharing and for a GNS
+zone, this will weaken the privacy assurances provided by the anonymous
+file-sharing protocol.
+
+Note that an ego is NOT bound to a GNUnet peer. There can be multiple
+egos for a single user, and users could (theoretically) share the
+private keys of an ego by copying the respective private keys.
+
+.. _Namespaces:
+
+Namespaces
+^^^^^^^^^^
+
+A namespace is a set of files that were signed by the same ego. Today,
+namespaces are implemented independently of GNS zones, but in the future
+we plan to merge the two such that a GNS zone can basically contain
+files using a file-sharing specific record type.
+
+Files (or directories) that have been signed and placed into a namespace
+can be updated. Updates are identified as authentic if the same secret
+key was used to sign the update.
+
+.. _Advertisements:
+
+Advertisements
+^^^^^^^^^^^^^^
+
+Advertisements are used to notify other users about the existence of a
+namespace. Advertisements are propagated using the normal keyword
+search. When an advertisement is received (in response to a search), the
+namespace is added to the list of namespaces available in the
+namespace-search dialogs of gnunet-fs-gtk and printed by
+``gnunet-identity``. Whenever a namespace is created, an appropriate
+advertisement can be generated. The default keyword for the advertising
+of namespaces is \"namespace\".
+
+.. _Anonymity-level:
+
+Anonymity level
+^^^^^^^^^^^^^^^
+
+The anonymity level determines how hard it should be for an adversary to
+determine the identity of the publisher or the searcher/downloader. An
+anonymity level of zero means that anonymity is not required. The
+default anonymity level of \"1\" means that anonymous routing is
+desired, but no particular amount of cover traffic is necessary. A
+powerful adversary might thus still be able to deduce the origin of the
+traffic using traffic analysis. Specifying higher anonymity levels
+increases the amount of cover traffic required.
+
+The specific numeric value (for anonymity levels above 1) is simple:
+Given an anonymity level L (above 1), each request FS makes on your
+behalf must be hidden in L-1 equivalent requests of cover traffic
+(traffic your peer routes for others) in the same time-period. The
+time-period is twice the average delay by which GNUnet artificially
+delays traffic.
+
+While higher anonymity levels may offer better privacy, they can also
+significantly hurt performance.
+
+.. _Content-Priority:
+
+Content Priority
+^^^^^^^^^^^^^^^^
+
+Depending on the peer's configuration, GNUnet peers migrate content
+between peers. Content in this sense are individual blocks of a file,
+not necessarily entire files. When peers run out of space (due to local
+publishing operations or due to migration of content from other peers),
+blocks sometimes need to be discarded. GNUnet first always discards
+expired blocks (typically, blocks are published with an expiration of
+about two years in the future; this is another option). If there is
+still not enough space, GNUnet discards the blocks with the lowest
+priority. The priority of a block is decided by its popularity (in terms
+of requests from peers we trust) and, in case of blocks published
+locally, the base-priority that was specified by the user when the block
+was published initially.
+
+.. _Replication:
+
+Replication
+^^^^^^^^^^^
+
+When peers migrate content to other systems, the replication level of a
+block is used to decide which blocks need to be migrated most urgently.
+GNUnet will always push the block with the highest replication level
+into the network, and then decrement the replication level by one. If
+all blocks reach replication level zero, the selection is simply random.
+
+.. _Namespace-Management:
+
+Namespace Management
+~~~~~~~~~~~~~~~~~~~~
+
+The ``gnunet-identity`` tool can be used to create egos. By default,
+``gnunet-identity --display`` simply lists all locally available egos.
+
+.. _Creating-Egos:
+
+Creating Egos
+^^^^^^^^^^^^^
+
+With the ``--create=NICK`` option it can also be used to create a new
+ego. An ego is the virtual identity of the entity in control of a
+namespace or GNS zone. Anyone can create any number of egos. The
+provided NICK name automatically corresponds to a GNU Name System domain
+name. Thus, henceforth name resolution for any name ending in ".NICK"
+will use the NICK's zone. You should avoid using NICKs that collide with
+well-known DNS names.
+
+Currently, the IDENTITY subsystem supports two types of identity keys:
+ECDSA and EdDSA. By default, ECDSA identities are creates with ECDSA
+keys. In order to create an identity with EdDSA keys, you can use the
+``--eddsa`` flag.
+
+.. _Deleting-Egos:
+
+Deleting Egos
+^^^^^^^^^^^^^
+
+With the ``-D NICK`` option egos can be deleted. Once the ego has been
+deleted it is impossible to add content to the corresponding namespace
+or zone. However, the existing GNS zone data is currently not dropped.
+This may change in the future.
+
+Deleting the pseudonym does not make the namespace or any content in it
+unavailable.
+
+.. _File_002dSharing-URIs:
+
+File-Sharing URIs
+~~~~~~~~~~~~~~~~~
+
+GNUnet (currently) uses four different types of URIs for file-sharing.
+They all begin with \"gnunet://fs/\". This section describes the four
+different URI types in detail.
+
+For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to denote
+whitespace between words. Keywords must contain a balanced number of
+double quotes. Doubles quotes can not be used in the actual keywords.
+This means that the string '\"\"foo bar\"\"' will be turned into two
+OR-ed keywords 'foo' and 'bar', not into '\"foo bar\"'.
+
+.. _Encoding-of-hash-values-in-URIs:
+
+Encoding of hash values in URIs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most URIs include some hash values. Hashes are encoded using base32hex
+(RFC 2938).
+
+chk-uri
+.. _Content-Hash-Key-_0028chk_0029:
+
+Content Hash Key (chk)
+^^^^^^^^^^^^^^^^^^^^^^
+
+A chk-URI is used to (uniquely) identify a file or directory and to
+allow peers to download the file. Files are stored in GNUnet as a tree
+of encrypted blocks. The chk-URI thus contains the information to
+download and decrypt those blocks. A chk-URI has the format
+\"gnunet://fs/chk/KEYHASH.QUERYHASH.SIZE\". Here, \"SIZE\" is the size
+of the file (which allows a peer to determine the shape of the tree),
+KEYHASH is the key used to decrypt the file (also the hash of the
+plaintext of the top block) and QUERYHASH is the query used to request
+the top-level block (also the hash of the encrypted block).
+
+loc-uri
+.. _Location-identifiers-_0028loc_0029:
+
+Location identifiers (loc)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For non-anonymous file-sharing, loc-URIs are used to specify which peer
+is offering the data (in addition to specifying all of the data from a
+chk-URI). Location identifiers include a digital signature of the peer
+to affirm that the peer is truly the origin of the data. The format is
+\"gnunet://fs/loc/KEYHASH.QUERYHASH.SIZE.PEER.SIG.EXPTIME\". Here,
+\"PEER\" is the public key of the peer (in GNUnet format in base32hex),
+SIG is the RSA signature (in GNUnet format in base32hex) and EXPTIME
+specifies when the signature expires (in milliseconds after 1970).
+
+ksk-uri
+.. _Keyword-queries-_0028ksk_0029:
+
+Keyword queries (ksk)
+^^^^^^^^^^^^^^^^^^^^^
+
+A keyword-URI is used to specify that the desired operation is the
+search using a particular keyword. The format is simply
+\"gnunet://fs/ksk/KEYWORD\". Non-ASCII characters can be specified using
+the typical URI-encoding (using hex values) from HTTP. \"+\" can be used
+to specify multiple keywords (which are then logically \"OR\"-ed in the
+search, results matching both keywords are given a higher rank):
+\"gnunet://fs/ksk/KEYWORD1+KEYWORD2\". ksk-URIs must not begin or end
+with the plus ('+') character. Furthermore they must not contain '++'.
+
+sks-uri
+.. _Namespace-content-_0028sks_0029:
+
+Namespace content (sks)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+**Please note that the text in this subsection is outdated and needs**
+**to be rewritten for version 0.10!** **This especially concerns the
+terminology of Pseudonym/Ego/Identity.**
+
+Namespaces are sets of files that have been approved by some (usually
+pseudonymous) user --- typically by that user publishing all of the
+files together. A file can be in many namespaces. A file is in a
+namespace if the owner of the ego (aka the namespace's private key)
+signs the CHK of the file cryptographically. An SKS-URI is used to
+search a namespace. The result is a block containing meta data, the CHK
+and the namespace owner's signature. The format of a sks-URI is
+\"gnunet://fs/sks/NAMESPACE/IDENTIFIER\". Here, \"NAMESPACE\" is the
+public key for the namespace. \"IDENTIFIER\" is a freely chosen keyword
+(or password!). A commonly used identifier is \"root\" which by
+convention refers to some kind of index or other entry point into the
+namespace.
+
+
diff --git a/man_users/index.rst b/man_users/index.rst
@@ -22,3 +22,7 @@ welcome.
    gns
    reclaim
    fs
+   vpn
+   messenger
+   configuration
+
diff --git a/man_users/messenger.rst b/man_users/messenger.rst
@@ -0,0 +1,153 @@
+.. _Using-the-GNUnet-Messenger:
+
+Messenger
+---------
+
+The GNUnet Messenger subsystem allows decentralized message-based
+communication inside of so called rooms. Each room can be hosted by a
+variable amount of peers. Every member of a room has the possibility to
+host the room on its own peer. A peer allows any amount of members to
+join a room. The amount of members in a room is not restricted.
+
+Messages in a room will be distributed between all peers hosting the
+room or being internally (in context of the messenger service) connected
+to a hosting peer. All received or sent messages will be stored on any
+peer locally which is hosting the respective room or is internally
+connected to such a hosting peer.
+
+The Messenger service is built on the CADET subsystem to make internal
+connections between peers using a reliable and encrypted transmission.
+Additionally the service uses a discrete padding to few different sizes.
+So kinds of messages and potential content can't be identified by the
+size of traffic from any attacker being unable to break the encryption
+of the transmission layer.
+
+Another feature is additional end-to-end encryption for selected
+messages which uses the public key of another member (the receiver) to
+encrypt the message. Therefore it is ensured that only the selected
+member can read its content. This will also use additional padding.
+
+.. _Current-state:
+
+Current state
+~~~~~~~~~~~~~
+
+Currently there is only a simplistic CLI application available to use
+the messenger service. You can use this application with the
+``gnunet-messenger`` command.
+
+This application was designed for testing purposes and it does not
+provide full functionality in the current state. It is planned to
+replace this CLI application in later stages with a fully featured one
+using a client-side library designed for messenger applications.
+
+.. _Entering-a-room:
+
+Entering a room
+~~~~~~~~~~~~~~~
+
+You can enter any room by its ROOMKEY and any PEERIDENTITY of a hosting
+peer. Optionally you can provide any IDENTITY which can represent a
+local ego by its name.
+
+::
+
+   $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY
+
+A PEERIDENTITY gets entered in encoded form. You can get your own peer
+ID by using the ``gnunet-peerinfo`` command:
+
+::
+
+   $ gnunet-peerinfo -s
+
+A ROOMKEY gets entered in readable text form. The service will then hash
+the entered ROOMKEY and use the result as shared secret for transmission
+through the CADET submodule. You can also optionally leave out the '-r'
+parameter and the ROOMKEY to use the zeroed hash instead.
+
+If no IDENTITY is provided you will not send any name to others, you
+will be referred as \"anonymous\" instead and use the anonymous ego. If
+you provide any IDENTITY a matching ego will be used to sign your
+messages. If there is no matching ego you will use the anonymous ego
+instead. The provided IDENTITY will be distributed as your name for the
+service in any case.
+
+.. _Opening-a-room:
+
+Opening a room
+~~~~~~~~~~~~~~
+
+You can open any room in a similar way to entering it. You just have to
+leave out the '-d' parameter and the PEERIDENTITY of the hosting peer.
+
+::
+
+   $ gnunet-messenger [-e IDENTITY] -r ROOMKEY
+
+Providing ROOMKEY and IDENTITY is identical to entering a room. Opening
+a room will also make your peer to a host of this room. So others can
+enter the room through your peer if they have the required ROOMKEY and
+your peer ID.
+
+If you want to use the zeroed hash as shared secret key for the room you
+can also leave it out as well:
+
+::
+
+   $ gnunet-messenger
+
+.. _Messaging-in-a-room:
+
+Messaging in a room
+~~~~~~~~~~~~~~~~~~~
+
+Once joined a room by entering it or opening it you can write text-based
+messages which will be distributed between all internally conntected
+peers. All sent messages will be displayed in the same way as received
+messages.
+
+This relates to the internal handling of sent and received messages
+being mostly identical on application layer. Every handled message will
+be represented visually depending on its kind, content and sender. A
+sender can usually be identified by the encoded member ID or their name.
+
+.. code-block:: text
+
+   [17X37K] * 'anonymous' says: "hey"
+
+.. _Private-messaging:
+
+Private messaging
+~~~~~~~~~~~~~~~~~
+
+As referred in the introduction the service allows sending private
+messages with additional end-to-end encryption. These messages will be
+visually represented by messages of the kind 'PRIVATE' in case they
+can't be decrypted with your used ego. Members who can't decrypt the
+message can potentially only identify its sender but they can't identify
+its receiver.
+
+.. code-block:: text
+
+   [17X37K] ~ message: PRIVATE
+
+If they can be decrypted they will appear as their secret message
+instead but marked visually.
+
+.. code-block:: text
+
+   [17X37K] ** 'anonymous' says: "hey"
+
+Currently you can only activate sending such encrypted text messages
+instead of usual text messages by adding the '-p' parameter:
+
+.. code-block:: shell
+
+   $ gnunet-messenger [-e IDENTITY] -d PEERIDENTITY -r ROOMKEY -p
+
+Notice that you can only send such encrypted messages to members who use
+an ego which is not publicly known as the anonymous ego to ensure
+transparency. If any user could decrypt these messages they would not be
+private. So as receiver of such messages the IDENTITY is required and it
+has to match a local ego.
diff --git a/man_users/reclaim.rst b/man_users/reclaim.rst
@@ -1,3 +1,281 @@
+.. _reclaimID-Identity-Provider:
+
 re:claimID
 ----------
 
+The re:claimID Identity Provider (IdP) is a decentralized IdP service.
+It allows its users to manage and authorize third parties to access
+their identity attributes such as email or shipping addresses.
+
+It basically mimics the concepts of centralized IdPs, such as those
+offered by Google or Facebook. Like other IdPs, reclaimID features an
+(optional) OpenID Connect 1.0-compliant protocol layer that can be used
+for websites to integrate reclaimID as an Identity Provider with little
+effort.
+
+.. _Managing-Attributes:
+
+Managing Attributes
+~~~~~~~~~~~~~~~~~~~
+
+Before adding attributes to an identity, you must first create an ego:
+
+::
+
+   $ gnunet-identity --create="user"
+
+Henceforth, you can manage a new user profile of the user "user".
+
+To add an email address to your user profile, simply use the
+``gnunet-reclaim`` command line tool::
+
+::
+
+   $ gnunet-reclaim -e "user" -a "email" -V "username@example.gnunet"
+
+All of your attributes can be listed using the ``gnunet-reclaim``
+command line tool as well:
+
+::
+
+   $ gnunet-reclaim -e "user" -D
+
+Currently, and by default, attribute values are interpreted as plain
+text. In the future there might be more value types such as X.509
+certificate credentials.
+
+.. _Managing-Credentials:
+
+Managing Credentials
+~~~~~~~~~~~~~~~~~~~~
+
+Attribute values may reference a claim in a third party attested
+credential. Such a credential can have a variety of formats such as
+JSON-Web-Tokens or X.509 certificates. Currently, reclaimID only
+supports JSON-Web-Token credentials.
+
+To add a credential to your user profile, invoke the ``gnunet-reclaim``
+command line tool as follows:
+
+::
+
+   $ gnunet-reclaim -e "user"\
+                    --credential-name="email"\
+                    --credential-type="JWT"\
+                    --value="ey..."
+
+All of your credentials can be listed using the ``gnunet-reclaim``
+command line tool as well:
+
+::
+
+   $ gnunet-reclaim -e "user" --credentials
+
+In order to add an attribe backed by a credential, specify the attribute
+value as the claim name in the credential to reference along with the
+credential ID:
+
+::
+
+   $ gnunet-reclaim -e "user"\
+                    --add="email"\
+                    --value="verified_email"\
+                    --credential-id="<CREDENTIAL_ID>"
+
+.. _Sharing-Attributes-with-Third-Parties:
+
+Sharing Attributes with Third Parties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to allow a third party such as a website or friend to access
+to your attributes (or a subset thereof) execute:
+
+::
+
+   $ TICKET=$(gnunet-reclaim -e "user"\
+                             -r "$RP_KEY"\
+                             -i "attribute1,attribute2,...")
+
+The command will return a \"ticket\" string. You must give $TICKET to
+the requesting third party.
+
+$RP_KEY is the public key of the third party and
+\"attribute1,attribute2,\...\" is a comma-separated list of attribute
+names, such as \"email,name,\...\", that you want to share.
+
+The third party may retrieve the key in string format for use in the
+above call using \"gnunet-identity\":
+
+.. code-block:: shell
+
+   $ RP_KEY=$(gnunet-identity -d | grep "relyingparty" | awk '{print $3}')
+
+The third party can then retrieve your shared identity attributes using:
+
+.. code-block:: shell
+
+   $ gnunet-reclaim -e "relyingparty" -C "ticket"
+
+Where \"relyingparty\" is the name for the identity behind $RP_KEY that
+the requesting party is using. This will retrieve and list the shared
+identity attributes. The above command will also work if the user is
+currently offline since the attributes are retrieved from GNS. Further,
+$TICKET can be re-used later to retrieve up-to-date attributes in case
+\"friend\" has changed the value(s). For instance, because his email
+address changed.
+
+To list all given authorizations (tickets) you can execute:
+
+.. code-block:: shell
+
+   $ gnunet-reclaim -e "user" -T
+
+.. _Revoking-Authorizations-of-Third-Parties:
+
+Revoking Authorizations of Third Parties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to revoke the access of a third party to your attributes you
+can execute:
+
+::
+
+   $ gnunet-reclaim -e "user" -R $TICKET
+
+This will prevent the third party from accessing the attribute in the
+future. Please note that if the third party has previously accessed the
+attribute, there is not way in which the system could have prevented the
+thiry party from storing the data. As such, only access to updated data
+in the future can be revoked. This behaviour is \_exactly the same\_ as
+with other IdPs.
+
+.. _OpenID-Connect:
+
+OpenID Connect
+~~~~~~~~~~~~~~
+
+There is an
+`https://openid.net/specs/openid-connect-core-1_0.html <OpenID Connect>`__
+API for use with re:claimID. However, its use is quite complicated to
+setup.
+
+::
+
+   https://api.reclaim/openid/authorize
+   http://localhost:7776/openid/token
+   http://localhost:7776/openid/userinfo
+   http://localhost:7776/openid/login
+
+The token endpoint is protected using HTTP basic authentication. You can
+authenticate using any username and the password configured under:
+
+::
+
+   $ gnunet-config -s reclaim-rest-plugin -o OIDC_CLIENT_SECRET
+
+The authorize endpoint is protected using a Cookie which can be obtained
+through a request against the login endpoint. This functionality is
+meant to be used in the context of the OpenID Connect authorization flow
+to collect user consent interactively. Without a Cookie, the authorize
+endpoint redirects to a URI configured under:
+
+::
+
+   $ gnunet-config -s reclaim-rest-plugin -o ADDRESS
+
+The token endpoint is protected using OAuth2 and expects the grant which
+is retrieved from the authorization endpoint according to the standard.
+
+The userinfo endpoint is protected using OAuth2 and expects a bearer
+access token which is retrieved from a token request.
+
+In order to make use of OpenID Connect flows as a user, you need to
+install the browser plugin:
+
+-  `Firefox Add-on <https://addons.mozilla.org/addon/reclaimid/>`__
+
+-  `Chrome Web
+   Store <https://chrome.google.com/webstore/detail/reclaimid/jiogompmdejcnacmlnjhnaicgkefcfll>`__
+
+In order to create and register an OpenID Connect client as a relying
+party, you need to execute the following steps:
+
+::
+
+   $ gnunet-identity -C <client_name>
+   $ gnunet-namestore -z <client_name> -a -n "@" -t RECLAIM_OIDC_REDIRECT -V <redirect_uri> -e 1d -p
+   $ gnunet-namestore -z <client_name> -a -n "@" -t RECLAIM_OIDC_CLIENT -V "My OIDC Client" -e 1d -p
+
+The \"client_id\" for use in OpenID Connect is the public key of the
+client as displayed using:
+
+.. code-block:: shell
+
+   $ gnunet-identity -d grep "relyingparty" | awk '{print $3}'
+
+The RECLAIM_OIDC_REDIRECT record contains your website redirect URI. You
+may use any globally unique DNS or GNS URI. The RECLAIM_OIDC_CLIENT
+record represents the client description which whill be displayed to
+users in an authorization request.
+
+Any website or relying party must use the authorization endpoint
+https://api.reclaim/openid/authorize in its authorization redirects,
+e.g.
+
+.. code-block:: html
+
+   <a href="https://api.reclaim/openid/authorize?client_id=<PKEY>\
+                                                &scope=openid email\
+                                                &redirect_uri=<redirect_uri>\
+                                                &nonce=<random>">Login</a>
+
+This will direct the user's browser onto his local reclaimID instance.
+After giving consent, you will be provided with the OpenID Connect
+authorization code according to the specifications at your provided
+redirect URI.
+
+The ID Tokens issues by the token endpoints are signed using HS512 with
+the shared secret configured under:
+
+::
+
+   $ gnunet-config -s reclaim-rest-plugin -o JWT_SECRET
+
+The authorization code flow optionally supports `Proof Key for Code
+Exchange <https://tools.ietf.org/html/rfc7636>`__. If PKCE is used, the
+client does not need to authenticate against the token endpoint.
+
+.. _Providing-Third-Party-Attestation:
+
+Providing Third Party Attestation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are running an identity provider (IdP) service you may be able to
+support providing credentials for re:claimID users. IdPs can issue JWT
+credentials as long as they support OpenID Connect and `OpenID Connect
+Discovery <https://openid.net/specs/openid-connect-discovery-1_0.html>`__.
+
+In order to allow users to import attributes through the re:claimID user
+interface, you need to register the following public OAuth2/OIDC client:
+
+-  client_id: reclaimid
+
+-  client_secret: none
+
+-  redirect_uri: https://ui.reclaim (The URI of the re:claimID
+   webextension)
+
+-  grant_type: authorization_code with PKCE
+   (`RFC7636 <https://tools.ietf.org/html/rfc7636>`__)
+
+-  scopes: all you want to offer.
+
+-  id_token: JWT
+
+When your users add an attribute with name \"email\" which supports
+webfinger discovery they will be prompted with the option to retrieve
+the OpenID Connect ID Token through the user interface.
+
+
+
+
diff --git a/man_users/vpn.rst b/man_users/vpn.rst
@@ -0,0 +1,179 @@
+.. _Using-the-Virtual-Public-Network:
+
+Virtual Public Network
+----------------------
+
+Using the GNUnet Virtual Public Network (VPN) application you can tunnel
+IP traffic over GNUnet. Moreover, the VPN comes with built-in protocol
+translation and DNS-ALG support, enabling IPv4-to-IPv6 protocol
+translation (in both directions). This chapter documents how to use the
+GNUnet VPN.
+
+The first thing to note about the GNUnet VPN is that it is a public
+network. All participating peers can participate and there is no secret
+key to control access. So unlike common virtual private networks, the
+GNUnet VPN is not useful as a means to provide a \"private\" network
+abstraction over the Internet. The GNUnet VPN is a virtual network in
+the sense that it is an overlay over the Internet, using its own routing
+mechanisms and can also use an internal addressing scheme. The GNUnet
+VPN is an Internet underlay --- TCP/IP applications run on top of it.
+
+The VPN is currently only supported on GNU/Linux systems. Support for
+operating systems that support TUN (such as FreeBSD) should be easy to
+add (or might not even require any coding at all --- we just did not
+test this so far). Support for other operating systems would require
+re-writing the code to create virtual network interfaces and to
+intercept DNS requests.
+
+The VPN does not provide good anonymity. While requests are routed over
+the GNUnet network, other peers can directly see the source and
+destination of each (encapsulated) IP packet. Finally, if you use the
+VPN to access Internet services, the peer sending the request to the
+Internet will be able to observe and even alter the IP traffic. We will
+discuss additional security implications of using the VPN later in this
+chapter.
+
+.. _Setting-up-an-Exit-node:
+
+Setting up an Exit node
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Any useful operation with the VPN requires the existence of an exit node
+in the GNUnet Peer-to-Peer network. Exit functionality can only be
+enabled on peers that have regular Internet access. If you want to play
+around with the VPN or support the network, we encourage you to setup
+exit nodes. This chapter documents how to setup an exit node.
+
+There are four types of exit functions an exit node can provide, and
+using the GNUnet VPN to access the Internet will only work nicely if the
+first three types are provided somewhere in the network. The four exit
+functions are:
+
+-  DNS: allow other peers to use your DNS resolver
+
+-  IPv4: allow other peers to access your IPv4 Internet connection
+
+-  IPv6: allow other peers to access your IPv6 Internet connection
+
+-  Local service: allow other peers to access a specific TCP or UDP
+   service your peer is providing
+
+By enabling \"exit\" in gnunet-setup and checking the respective boxes
+in the \"exit\" tab, you can easily choose which of the above exit
+functions you want to support.
+
+Note, however, that by supporting the first three functions you will
+allow arbitrary other GNUnet users to access the Internet via your
+system. This is somewhat similar to running a Tor exit node. The
+Torproject has a nice article about what to consider if you want to do
+this here. We believe that generally running a DNS exit node is
+completely harmless.
+
+The exit node configuration does currently not allow you to restrict the
+Internet traffic that leaves your system. In particular, you cannot
+exclude SMTP traffic (or block port 25) or limit to HTTP traffic using
+the GNUnet configuration. However, you can use your host firewall to
+restrict outbound connections from the virtual tunnel interface. This is
+highly recommended. In the future, we plan to offer a wider range of
+configuration options for exit nodes.
+
+Note that by running an exit node GNUnet will configure your kernel to
+perform IP-forwarding (for IPv6) and NAT (for IPv4) so that the traffic
+from the virtual interface can be routed to the Internet. In order to
+provide an IPv6-exit, you need to have a subnet routed to your host's
+external network interface and assign a subrange of that subnet to the
+GNUnet exit's TUN interface.
+
+When running a local service, you should make sure that the local
+service is (also) bound to the IP address of your EXIT interface (e.g.
+169.254.86.1). It will NOT work if your local service is just bound to
+loopback. You may also want to create a \"VPN\" record in your zone of
+the GNU Name System to make it easy for others to access your service
+via a name instead of just the full service descriptor. Note that the
+identifier you assign the service can serve as a passphrase or shared
+secret, clients connecting to the service must somehow learn the
+service's name. VPN records in the GNU Name System can make this easier.
+
+.. _Fedora-and-the-Firewall:
+
+Fedora and the Firewall
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When using an exit node on Fedora 15, the standard firewall can create
+trouble even when not really exiting the local system! For IPv4, the
+standard rules seem fine. However, for IPv6 the standard rules prohibit
+traffic from the network range of the virtual interface created by the
+exit daemon to the local IPv6 address of the same interface (which is
+essentially loopback traffic, so you might suspect that a standard
+firewall would leave this traffic alone). However, as somehow for IPv6
+the traffic is not recognized as originating from the local system (and
+as the connection is not already \"established\"), the firewall drops
+the traffic. You should still get ICMPv6 packets back, but that's
+obviously not very useful.
+
+Possible ways to fix this include disabling the firewall (do you have a
+good reason for having it on?) or disabling the firewall at least for
+the GNUnet exit interface (or the respective IPv4/IPv6 address range).
+The best way to diagnose these kinds of problems in general involves
+setting the firewall to REJECT instead of DROP and to watch the traffic
+using wireshark (or tcpdump) to see if ICMP messages are generated when
+running some tests that should work.
+
+.. _Setting-up-VPN-node-for-protocol-translation-and-tunneling:
+
+Setting up VPN node for protocol translation and tunneling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The GNUnet VPN/PT subsystem enables you to tunnel IP traffic over the
+VPN to an exit node, from where it can then be forwarded to the
+Internet. This section documents how to setup VPN/PT on a node. Note
+that you can enable both the VPN and an exit on the same peer. In this
+case, IP traffic from your system may enter your peer's VPN and leave
+your peer's exit. This can be useful as a means to do protocol
+translation. For example, you might have an application that supports
+only IPv4 but needs to access an IPv6-only site. In this case, GNUnet
+would perform 4to6 protocol translation between the VPN (IPv4) and the
+Exit (IPv6). Similarly, 6to4 protocol translation is also possible.
+However, the primary use for GNUnet would be to access an Internet
+service running with an IP version that is not supported by your ISP. In
+this case, your IP traffic would be routed via GNUnet to a peer that has
+access to the Internet with the desired IP version.
+
+Setting up an entry node into the GNUnet VPN primarily requires you to
+enable the \"VPN/PT\" option in \"gnunet-setup\". This will launch the
+\"gnunet-service-vpn\", \"gnunet-service-dns\" and \"gnunet-daemon-pt\"
+processes. The \"gnunet-service-vpn\" will create a virtual interface
+which will be used as the target for your IP traffic that enters the
+VPN. Additionally, a second virtual interface will be created by the
+\"gnunet-service-dns\" for your DNS traffic. You will then need to
+specify which traffic you want to tunnel over GNUnet. If your ISP only
+provides you with IPv4 or IPv6-access, you may choose to tunnel the
+other IP protocol over the GNUnet VPN. If you do not have an ISP (and
+are connected to other GNUnet peers via WLAN), you can also choose to
+tunnel all IP traffic over GNUnet. This might also provide you with some
+anonymity. After you enable the respective options and restart your
+peer, your Internet traffic should be tunneled over the GNUnet VPN.
+
+The GNUnet VPN uses DNS-ALG to hijack your IP traffic. Whenever an
+application resolves a hostname (like 'gnunet.org'), the
+\"gnunet-daemon-pt\" will instruct the \"gnunet-service-dns\" to
+intercept the request (possibly route it over GNUnet as well) and
+replace the normal answer with an IP in the range of the VPN's
+interface. \"gnunet-daemon-pt\" will then tell \"gnunet-service-vpn\" to
+forward all traffic it receives on the TUN interface via the VPN to the
+original destination.
+
+For applications that do not use DNS, you can also manually create such
+a mapping using the gnunet-vpn command-line tool. Here, you specify the
+desired address family of the result (e.g. \"-4\"), and the intended
+target IP on the Internet (e.g. \"-i 131.159.74.67\") and \"gnunet-vpn\"
+will tell you which IP address in the range of your VPN tunnel was
+mapped.
+
+``gnunet-vpn`` can also be used to access \"internal\" services offered
+by GNUnet nodes. So if you happen to know a peer and a 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.
+