From bdce99417112727263204dfc3194e926d6f96b03 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Julius=20B=C3=BCnger?= Date: Thu, 28 Jun 2018 10:36:39 +0200 Subject: [PATCH] doc: move check install and configuration to installation --- doc/documentation/chapters/installation.texi | 2009 ++++++++++++++++++ doc/documentation/chapters/user.texi | 2007 ----------------- doc/documentation/gnunet.texi | 5 +- 3 files changed, 2010 insertions(+), 2011 deletions(-) diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi index d66d72ae5..f5e38fd3d 100644 --- a/doc/documentation/chapters/installation.texi +++ b/doc/documentation/chapters/installation.texi @@ -156,3 +156,2012 @@ USER_ONLY = NO [transport] PLUGINS = tcp @end example + + + + + + +@node MOVED FROM USER Checking the Installation +@section MOVED FROM USER Checking the Installation +@c %**end of header + +This section describes a quick, casual way to check if your GNUnet +installation works. However, if it does not, we do not cover +steps for recovery --- for this, please study the instructions +provided in the developer handbook as well as the system-specific +instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}. + + +@menu +* gnunet-gtk:: +* Statistics:: +* Peer Information:: +@end menu + +@cindex GNUnet GTK +@cindex GTK +@cindex GTK user interface +@node gnunet-gtk +@subsection gnunet-gtk +@c %**end of header + +The @command{gnunet-gtk} package contains several graphical +user interfaces for the respective GNUnet applications. +Currently these interfaces cover: + +@itemize @bullet +@item Statistics +@item Peer Information +@item GNU Name System +@item File Sharing +@item Identity Management +@item Conversation +@end itemize + +@node Statistics +@subsection Statistics +@c %**end of header + +First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. +You can do this from the command-line by typing + +@example +gnunet-statistics-gtk +@end example + +If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.} +is running correctly, you should see a bunch of lines, +all of which should be ``significantly'' above zero (at least if your +peer has been running for more than a few seconds). The lines indicate +how many other peers your peer is connected to (via different +mechanisms) and how large the entire overlay network is currently +estimated to be. The X-axis represents time (in seconds since the +start of @command{gnunet-gtk}). + +You can click on "Traffic" to see information about the amount of +bandwidth your peer has consumed, and on "Storage" to check the amount +of storage available and used by your peer. Note that "Traffic" is +plotted cumulatively, so you should see a strict upwards trend in the +traffic. + +@node Peer Information +@subsection Peer Information +@c %**end of header + +First, you should launch the graphical user interface. You can do +this from the command-line by typing + +@example +$ gnunet-peerinfo-gtk +@end example + +Once you have done this, you will see a list of known peers (by the +first four characters of their public key), their friend status (all +should be marked as not-friends initially), their connectivity (green +is connected, red is disconnected), assigned bandwidth, country of +origin (if determined) and address information. If hardly any peers +are listed and/or if there are very few peers with a green light for +connectivity, there is likely a problem with your network +configuration. + +@c NOTE: Inserted from Installation Handbook in original ``order'': +@c FIXME: Move this to User Handbook. +@node MOVED FROM USER The graphical configuration interface +@section MOVED FROM USER The graphical configuration interface + +If you also would like to use @command{gnunet-gtk} and +@command{gnunet-setup} (highly recommended for beginners), do: + +@menu +* Configuring your peer:: +* Configuring the Friend-to-Friend (F2F) mode:: +* Configuring the hostlist to bootstrap:: +* Configuration of the HOSTLIST proxy settings:: +* Configuring your peer to provide a hostlist :: +* Configuring the datastore:: +* Configuring the MySQL database:: +* Reasons for using MySQL:: +* Reasons for not using MySQL:: +* Setup Instructions:: +* Testing:: +* Performance Tuning:: +* Setup for running Testcases:: +* Configuring the Postgres database:: +* Reasons to use Postgres:: +* Reasons not to use Postgres:: +* Manual setup instructions:: +* Testing the setup manually:: +* Configuring the datacache:: +* Configuring the file-sharing service:: +* Configuring logging:: +* Configuring the transport service and plugins:: +* Configuring the WLAN transport plugin:: +* Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: +* Blacklisting peers:: +* Configuration of the HTTP and HTTPS transport plugins:: +* Configuring the GNU Name System:: +* Configuring the GNUnet VPN:: +* Bandwidth Configuration:: +* Configuring NAT:: +* Peer configuration for distributions:: +@end menu + +@node Configuring your peer +@subsection Configuring your peer + +This chapter will describe the various configuration options in GNUnet. + +The easiest way to configure your peer is to use the +@command{gnunet-setup} tool. +@command{gnunet-setup} is part of the @command{gnunet-gtk} +application. You might have to install it separately. + +Many of the specific sections from this chapter actually are linked from +within @command{gnunet-setup} to help you while using the setup tool. + +While you can also configure your peer by editing the configuration +file by hand, this is not recommended for anyone except for developers +as it requires a more in-depth understanding of the configuration files +and internal dependencies of GNUnet. + +@node Configuring the Friend-to-Friend (F2F) mode +@subsection Configuring the Friend-to-Friend (F2F) mode + +GNUnet knows three basic modes of operation: +@itemize @bullet +@item In standard "peer-to-peer" mode, +your peer will connect to any peer. +@item In the pure "friend-to-friend" +mode, your peer will ONLY connect to peers from a list of friends +specified in the configuration. +@item Finally, in mixed mode, +GNUnet will only connect to arbitrary peers if it +has at least a specified number of connections to friends. +@end itemize + +When configuring any of the F2F ("friend-to-friend") modes, +you first need to create a file with the peer identities +of your friends. Ask your friends to run + +@example +$ gnunet-peerinfo -sq +@end example + +@noindent +The resulting output of this command needs to be added to your +@file{friends} file, which is simply a plain text file with one line +per friend with the output from the above command. + +You then specify the location of your @file{friends} file in the +@code{FRIENDS} option of the "topology" section. + +Once you have created the @file{friends} file, you can tell GNUnet to only +connect to your friends by setting the @code{FRIENDS-ONLY} option +(again in the "topology" section) to YES. + +If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a +minimum number of friends to have (before connecting to arbitrary peers) +under the "MINIMUM-FRIENDS" option. + +If you want to operate in normal P2P-only mode, simply set +@code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. +This is the default. + +@node Configuring the hostlist to bootstrap +@subsection Configuring the hostlist to bootstrap + +After installing the software you need to get connected to the GNUnet +network. The configuration file included in your download is already +configured to connect you to the GNUnet network. +In this section the relevant configuration settings are explained. + +To get an initial connection to the GNUnet network and to get to know +peers already connected to the network you can use the so called +"bootstrap servers". +These servers can give you a list of peers connected to the network. +To use these bootstrap servers you have to configure the hostlist daemon +to activate bootstrapping. + +To activate bootstrapping, edit the @code{[hostlist]}-section in your +configuration file. You have to set the argument @command{-b} in the +options line: + +@example +[hostlist] +OPTIONS = -b +@end example + +Additionally you have to specify which server you want to use. +The default bootstrapping server is +"@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". +[^] To set the server you have to edit the line "SERVERS" in the hostlist +section. To use the default server you should set the lines to + +@example +SERVERS = http://v10.gnunet.org/hostlist [^] +@end example + +@noindent +To use bootstrapping your configuration file should include these lines: + +@example +[hostlist] +OPTIONS = -b +SERVERS = http://v10.gnunet.org/hostlist [^] +@end example + +@noindent +Besides using bootstrap servers you can configure your GNUnet peer to +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 @command{-e} +switch to the @code{OPTIONS} line in the hostlist section: + +@example +[hostlist] +OPTIONS = -b -e +@end example + +@noindent +Furthermore you can specify in which file the lists are saved. +To save the lists in the file @file{hostlists.file} just add the line: + +@example +HOSTLISTFILE = hostlists.file +@end example + +@noindent +Best practice is to activate both bootstrapping and hostlist learning. +So your configuration file should include these lines: + +@example +[hostlist] +OPTIONS = -b -e +HTTPPORT = 8080 +SERVERS = http://v10.gnunet.org/hostlist [^] +HOSTLISTFILE = $SERVICEHOME/hostlists.file +@end example + +@node Configuration of the HOSTLIST proxy settings +@subsection Configuration of the HOSTLIST proxy settings + +The hostlist client can be configured to use a proxy to connect to the +hostlist server. +This functionality can be configured in the configuration file directly +or using the @command{gnunet-setup} tool. + +The hostlist client supports the following proxy types at the moment: + +@itemize @bullet +@item HTTP and HTTP 1.0 only proxy +@item SOCKS 4/4a/5/5 with hostname +@end itemize + +In addition authentication at the proxy with username and password can be +configured. + +To configure proxy support for the hostlist client in the +@command{gnunet-setup} tool, select the "hostlist" tab and select +the appropriate proxy type. +The hostname or IP address (including port if required) has to be entered +in the "Proxy hostname" textbox. If required, enter username and password +in the "Proxy username" and "Proxy password" boxes. +Be aware that this information will be stored in the configuration in +plain text (TODO: Add explanation and generalize the part in Chapter 3.6 +about the encrypted home). + +To provide these options directly in the configuration, you can +enter the following settings in the @code{[hostlist]} section of +the configuration: + +@example +# Type of proxy server, +# Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME +# Default: HTTP +# PROXY_TYPE = HTTP + +# Hostname or IP of proxy server +# PROXY = +# User name for proxy server +# PROXY_USERNAME = +# User password for proxy server +# PROXY_PASSWORD = +@end example + +@node Configuring your peer to provide a hostlist +@subsection Configuring your peer to provide a hostlist + +If you operate a peer permanently connected to GNUnet you can configure +your peer to act as a hostlist server, providing other peers the list of +peers known to him. + +Your server can act as a bootstrap server and peers needing to obtain a +list of peers can contact it to download this list. +To download this hostlist the peer uses HTTP. +For this reason you have to build your peer with libgnurl (or libcurl) +and microhttpd support. + +To configure your peer to act as a bootstrap server you have to add the +@command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section +of your configuration file. +Besides that you have to specify a port number for the http server. +In conclusion you have to add the following lines: + +@example +[hostlist] +HTTPPORT = 12980 +OPTIONS = -p +@end example + +@noindent +If your peer acts as a bootstrap server other peers should know about +that. You can advertise the hostlist your are providing to other peers. +Peers connecting to your peer will get a message containing an +advertisement for your hostlist and the URL where it can be downloaded. +If this peer is in learning mode, it will test the hostlist and, in the +case it can obtain the list successfully, it will save it for +bootstrapping. + +To activate hostlist advertisement on your peer, you have to set the +following lines in your configuration file: + +@example +[hostlist] +EXTERNAL_DNS_NAME = example.org +HTTPPORT = 12981 +OPTIONS = -p -a +@end example + +@noindent +With this configuration your peer will a act as a bootstrap server and +advertise this hostlist to other peers connecting to it. +The URL used to download the list will be +@code{@uref{http://example.org:12981/, http://example.org:12981/}}. + +Please notice: + +@itemize @bullet +@item The hostlist is @b{not} human readable, so you should not try to +download it using your webbrowser. Just point your GNUnet peer to the +address! +@item Advertising without providing a hostlist does not make sense and +will not work. +@end itemize + +@node Configuring the datastore +@subsection Configuring the datastore + +The datastore is what GNUnet uses for long-term storage of file-sharing +data. Note that long-term does not mean 'forever' since content does have +an expiration date, and of course storage space is finite (and hence +sometimes content may have to be discarded). + +Use the @code{QUOTA} option to specify how many bytes of storage space +you are willing to dedicate to GNUnet. + +In addition to specifying the maximum space GNUnet is allowed to use for +the datastore, you need to specify which database GNUnet should use to do +so. Currently, you have the choice between sqLite, MySQL and Postgres. + +@node Configuring the MySQL database +@subsection Configuring the MySQL database + +This section describes how to setup the MySQL database for GNUnet. + +Note that the mysql plugin does NOT work with mysql before 4.1 since we +need prepared statements. +We are generally testing the code against MySQL 5.1 at this point. + +@node Reasons for using MySQL +@subsection Reasons for using MySQL + +@itemize @bullet + +@item On up-to-date hardware wher +mysql can be used comfortably, this module +will have better performance than the other database choices (according +to our tests). + +@item Its often possible to recover the mysql database from internal +inconsistencies. Some of the other databases do not support repair. +@end itemize + +@node Reasons for not using MySQL +@subsection Reasons for not using MySQL + +@itemize @bullet +@item Memory usage (likely not an issue if you have more than 1 GB) +@item Complex manual setup +@end itemize + +@node Setup Instructions +@subsection Setup Instructions + +@itemize @bullet + +@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for +@code{DATABASE} to @code{mysql}. + +@item Access mysql as root: + +@example +$ mysql -u root -p +@end example + +@noindent +and issue the following commands, replacing $USER with the username +that will be running @command{gnunet-arm} (so typically "gnunet"): + +@example +CREATE DATABASE gnunet; +GRANT select,insert,update,delete,create,alter,drop,create \ +temporary tables ON gnunet.* TO $USER@@localhost; +SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); +FLUSH PRIVILEGES; +@end example + +@item +In the $HOME directory of $USER, create a @file{.my.cnf} file with the +following lines + +@example +[client] +user=$USER +password=$the_password_you_like +@end example + +@end itemize + +That's it. Note that @file{.my.cnf} file is a slight security risk unless +its on a safe partition. The @file{$HOME/.my.cnf} can of course be +a symbolic link. +Luckily $USER has only privileges to mess up GNUnet's tables, +which should be pretty harmless. + +@node Testing +@subsection Testing + +You should briefly try if the database connection works. First, login +as $USER. Then use: + +@example +$ mysql -u $USER +mysql> use gnunet; +@end example + +@noindent +If you get the message + +@example +Database changed +@end example + +@noindent +it probably works. + +If you get + +@example +ERROR 2002: Can't connect to local MySQL server +through socket '/tmp/mysql.sock' (2) +@end example + +@noindent +it may be resolvable by + +@example +ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock +@end example + +@noindent +so there may be some additional trouble depending on your mysql setup. + +@node Performance Tuning +@subsection Performance Tuning + +For GNUnet, you probably want to set the option + +@example +innodb_flush_log_at_trx_commit = 0 +@end example + +@noindent +for a rather dramatic boost in MySQL performance. However, this reduces +the "safety" of your database as with this options you may loose +transactions during a power outage. +While this is totally harmless for GNUnet, the option applies to all +applications using MySQL. So you should set it if (and only if) GNUnet is +the only application on your system using MySQL. + +@node Setup for running Testcases +@subsection Setup for running Testcases + +If you want to run the testcases, you must create a second database +"gnunetcheck" with the same username and password. This database will +then be used for testing (@command{make check}). + +@node Configuring the Postgres database +@subsection Configuring the Postgres database + +This text describes how to setup the Postgres database for GNUnet. + +This Postgres plugin was developed for Postgres 8.3 but might work for +earlier versions as well. + +@node Reasons to use Postgres +@subsection Reasons to use Postgres + +@itemize @bullet +@item Easier to setup than MySQL +@item Real database +@end itemize + +@node Reasons not to use Postgres +@subsection Reasons not to use Postgres + +@itemize @bullet +@item Quite slow +@item Still some manual setup required +@end itemize + +@node Manual setup instructions +@subsection Manual setup instructions + +@itemize @bullet +@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for +@code{DATABASE} to @code{postgres}. +@item Access Postgres to create a user: + +@table @asis +@item with Postgres 8.x, use: + +@example +# su - postgres +$ createuser +@end example + +@noindent +and enter the name of the user running GNUnet for the role interactively. +Then, when prompted, do not set it to superuser, allow the creation of +databases, and do not allow the creation of new roles. + +@item with Postgres 9.x, use: + +@example +# su - postgres +$ createuser -d $GNUNET_USER +@end example + +@noindent +where $GNUNET_USER is the name of the user running GNUnet. + +@end table + + +@item +As that user (so typically as user "gnunet"), create a database (or two): + +@example +$ createdb gnunet +# this way you can run "make check" +$ createdb gnunetcheck +@end example + +@end itemize + +Now you should be able to start @code{gnunet-arm}. + +@node Testing the setup manually +@subsection Testing the setup manually + +You may want to try if the database connection works. First, again login +as the user who will run @command{gnunet-arm}. Then use: + +@example +$ psql gnunet # or gnunetcheck +gnunet=> \dt +@end example + +@noindent +If, after you have started @command{gnunet-arm} at least once, you get +a @code{gn090} table here, it probably works. + +@node Configuring the datacache +@subsection Configuring the datacache +@c %**end of header + +The datacache is what GNUnet uses for storing temporary data. This data is +expected to be wiped completely each time GNUnet is restarted (or the +system is rebooted). + +You need to specify how many bytes GNUnet is allowed to use for the +datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. +Furthermore, you need to specify which database backend should be used to +store the data. Currently, you have the choice between +sqLite, MySQL and Postgres. + +@node Configuring the file-sharing service +@subsection Configuring the file-sharing service + +In order to use GNUnet for file-sharing, you first need to make sure +that the file-sharing service is loaded. +This is done by setting the @code{START_ON_DEMAND} option in +section @code{[fs]} to "YES". Alternatively, you can run + +@example +$ gnunet-arm -i fs +@end example + +@noindent +to start the file-sharing service by hand. + +Except for configuring the database and the datacache the only important +option for file-sharing is content migration. + +Content migration allows your peer to cache content from other peers as +well as send out content stored on your system without explicit requests. +This content replication has positive and negative impacts on both system +performance and privacy. + +FIXME: discuss the trade-offs. Here is some older text about it... + +Setting this option to YES allows gnunetd to migrate data to the local +machine. Setting this option to YES is highly recommended for efficiency. +Its also the default. If you set this value to YES, GNUnet will store +content on your machine that you cannot decrypt. +While this may protect you from liability if the judge is sane, it may +not (IANAL). If you put illegal content on your machine yourself, setting +this option to YES will probably increase your chances to get away with it +since you can plausibly deny that you inserted the content. +Note that in either case, your anonymity would have to be broken first +(which may be possible depending on the size of the GNUnet network and the +strength of the adversary). + +@node Configuring logging +@subsection Configuring logging + +Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. +Using @code{-L}, a log level can be specified. With log level +@code{ERROR} only serious errors are logged. +The default log level is @code{WARNING} which causes anything of +concern to be logged. +Log level @code{INFO} can be used to log anything that might be +interesting information whereas +@code{DEBUG} can be used by developers to log debugging messages +(but you need to run @code{./configure} with +@code{--enable-logging=verbose} to get them compiled). +The @code{-l} option is used to specify the log file. + +Since most GNUnet services are managed by @code{gnunet-arm}, using the +@code{-l} or @code{-L} options directly is not possible. +Instead, they can be specified using the @code{OPTIONS} configuration +value in the respective section for the respective service. +In order to enable logging globally without editing the @code{OPTIONS} +values for each service, @command{gnunet-arm} supports a +@code{GLOBAL_POSTFIX} option. +The value specified here is given as an extra option to all services for +which the configuration does contain a service-specific @code{OPTIONS} +field. + +@code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which +is replaced by the name of the service that is being started. +Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences +starting with "$" anywhere in the string are expanded (according +to options in @code{PATHS}); this expansion otherwise is +only happening for filenames and then the "$" must be the +first character in the option. Both of these restrictions do +not apply to @code{GLOBAL_POSTFIX}. +Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} +disables both of these features. + +In summary, in order to get all services to log at level +@code{INFO} to log-files called @code{SERVICENAME-logs}, the +following global prefix should be used: + +@example +GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO +@end example + +@node Configuring the transport service and plugins +@subsection Configuring the transport service and plugins + +The transport service in GNUnet is responsible to maintain basic +connectivity to other peers. +Besides initiating and keeping connections alive it is also responsible +for address validation. + +The GNUnet transport supports more than one transport protocol. +These protocols are configured together with the transport service. + +The configuration section for the transport service itself is quite +similar to all the other services + +@example +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 +@end example + +Different are the settings for the plugins to load @code{PLUGINS}. +The first setting specifies which transport plugins to load. + +@itemize @bullet +@item transport-unix +A plugin for local only communication with UNIX domain sockets. Used for +testing and available on unix systems only. Just set the port + +@example +[transport-unix] +PORT = 22086 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-tcp +A plugin for communication with TCP. Set port to 0 for client mode with +outbound only connections + +@example +[transport-tcp] +# Use 0 to ONLY advertise as a peer behind NAT (no port binding) +PORT = 2086 +ADVERTISED_PORT = 2086 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +# Maximum number of open TCP connections allowed +MAX_CONNECTIONS = 128 +@end example + +@item transport-udp +A plugin for communication with UDP. Supports peer discovery using +broadcasts. + +@example +[transport-udp] +PORT = 2086 +BROADCAST = YES +BROADCAST_INTERVAL = 30 s +MAX_BPS = 1000000 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-http +HTTP and HTTPS support is split in two part: a client plugin initiating +outbound connections and a server part accepting connections from the +client. The client plugin just takes the maximum number of connections as +an argument. + +@example +[transport-http_client] +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@example +[transport-https_client] +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@noindent +The server has a port configured and the maximum 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 @code{EXTERNAL_HOSTNAME} setting. +The webserver under this address should forward the request to the peer +and the configure port. + +@example +[transport-http_server] +EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet +PORT = 1080 +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@example +[transport-https_server] +PORT = 4433 +CRYPTO_INIT = NORMAL +KEY_FILE = https.key +CERT_FILE = https.cert +MAX_CONNECTIONS = 128 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example + +@item transport-wlan + +The next section describes how to setup the WLAN plugin, +so here only the settings. Just specify the interface to use: + +@example +[transport-wlan] +# Name of the interface in monitor mode (typically monX) +INTERFACE = mon0 +# Real hardware, no testing +TESTMODE = 0 +TESTING_IGNORE_KEYS = ACCEPT_FROM; +@end example +@end itemize + +@node Configuring the WLAN transport plugin +@subsection Configuring the WLAN transport plugin + +The wlan transport plugin enables GNUnet to send and to receive data on a +wlan interface. +It has not to be connected to a wlan network as long as sender and +receiver are on the same channel. This enables you to get connection to +GNUnet where no internet access is possible, for example during +catastrophes or when censorship cuts you off from the internet. + + +@menu +* Requirements for the WLAN plugin:: +* Configuration:: +* Before starting GNUnet:: +* Limitations and known bugs:: +@end menu + + +@node Requirements for the WLAN plugin +@subsubsection Requirements for the WLAN plugin + +@itemize @bullet + +@item wlan network card with monitor support and packet injection +(see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) + +@item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with +2.6.35 and 2.6.38 + +@item Wlantools to create the a monitor interface, tested with airmon-ng +of the aircrack-ng package +@end itemize + +@node Configuration +@subsubsection Configuration + +There are the following options for the wlan plugin (they should be like +this in your default config file, you only need to adjust them if the +values are incorrect for your system) + +@example +# section for the wlan transport plugin +[transport-wlan] +# interface to use, more information in the +# "Before starting GNUnet" section of the handbook. +INTERFACE = mon0 +# testmode for developers: +# 0 use wlan interface, +#1 or 2 use loopback driver for tests 1 = server, 2 = client +TESTMODE = 0 +@end example + +@node Before starting GNUnet +@subsubsection Before starting GNUnet + +Before starting GNUnet, you have to make sure that your wlan interface is +in monitor mode. +One way to put the wlan interface into monitor mode (if your interface +name is wlan0) is by executing: + +@example +sudo airmon-ng start wlan0 +@end example + +@noindent +Here is an example what the result should look like: + +@example +Interface Chipset Driver +wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] +(monitor mode enabled on mon0) +@end example + +@noindent +The monitor interface is mon0 is the one that you have to put into the +configuration file. + +@node Limitations and known bugs +@subsubsection Limitations and known bugs + +Wlan speed is at the maximum of 1 Mbit/s because support for choosing the +wlan speed with packet injection was removed in newer kernels. +Please pester the kernel developers about fixing this. + +The interface channel depends on the wlan network that the card is +connected to. If no connection has been made since the start of the +computer, it is usually the first channel of the card. +Peers will only find each other and communicate if they are on the same +channel. Channels must be set manually, i.e. using: + +@example +iwconfig wlan0 channel 1 +@end example + +@node Configuring HTTP(S) reverse proxy functionality using Apache or nginx +@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx + +The HTTP plugin supports data transfer using reverse proxies. A reverse +proxy forwards the HTTP request he receives with a certain URL to another +webserver, here a GNUnet peer. + +So if you have a running Apache or nginx webserver you can configure it to +be a GNUnet reverse proxy. Especially if you have a well-known webiste +this improves censorship resistance since it looks as normal surfing +behaviour. + +To do so, you have to do two things: + +@itemize @bullet +@item Configure your webserver to forward the GNUnet HTTP traffic +@item Configure your GNUnet peer to announce the respective address +@end itemize + +As an example we want to use GNUnet peer running: + +@itemize @bullet + +@item HTTP server plugin on @code{gnunet.foo.org:1080} + +@item HTTPS server plugin on @code{gnunet.foo.org:4433} + +@item A apache or nginx webserver on +@uref{http://www.foo.org/, http://www.foo.org:80/} + +@item A apache or nginx webserver on https://www.foo.org:443/ +@end itemize + +And we want the webserver to accept GNUnet traffic under +@code{http://www.foo.org/bar/}. The required steps are described here: + +@menu +* Reverse Proxy - Configure your Apache2 HTTP webserver:: +* Reverse Proxy - Configure your Apache2 HTTPS webserver:: +* Reverse Proxy - Configure your nginx HTTPS webserver:: +* Reverse Proxy - Configure your nginx HTTP webserver:: +* Reverse Proxy - Configure your GNUnet peer:: +@end menu + +@node Reverse Proxy - Configure your Apache2 HTTP webserver +@subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver + +First of all you need mod_proxy installed. + +Edit your webserver configuration. Edit +@code{/etc/apache2/apache2.conf} or the site-specific configuration file. + +In the respective @code{server config},@code{virtual host} or +@code{directory} section add the following lines: + +@example +ProxyTimeout 300 +ProxyRequests Off + +ProxyPass http://gnunet.foo.org:1080/ +ProxyPassReverse http://gnunet.foo.org:1080/ + +@end example + +@node Reverse Proxy - Configure your Apache2 HTTPS webserver +@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver + +We assume that you already have an HTTPS server running, if not please +check how to configure a HTTPS host. An uncomplicated to use example +is the example configuration file for Apache2/HTTPD provided in +@file{apache2/sites-available/default-ssl}. + +In the respective HTTPS @code{server config},@code{virtual host} or +@code{directory} section add the following lines: + +@example +SSLProxyEngine On +ProxyTimeout 300 +ProxyRequests Off + +ProxyPass https://gnunet.foo.org:4433/ +ProxyPassReverse https://gnunet.foo.org:4433/ + +@end example + +@noindent +More information about the apache mod_proxy configuration can be found +in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}} + +@node Reverse Proxy - Configure your nginx HTTPS webserver +@subsubsection Reverse Proxy - Configure your nginx HTTPS webserver + +Since nginx does not support chunked encoding, you first of all have to +install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}} + +To enable chunkin add: + +@example +chunkin on; +error_page 411 = @@my_411_error; +location @@my_411_error @{ +chunkin_resume; +@} +@end example + +@noindent +Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or +the site-specific configuration file. + +In the @code{server} section add: + +@example +location /bar/ @{ +proxy_pass http://gnunet.foo.org:1080/; +proxy_buffering off; +proxy_connect_timeout 5; # more than http_server +proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout +proxy_http_version 1.1; # 1.0 default +proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; +@} +@end example + +@node Reverse Proxy - Configure your nginx HTTP webserver +@subsubsection Reverse Proxy - Configure your nginx HTTP webserver + +Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or +the site-specific configuration file. + +In the @code{server} section add: + +@example +ssl_session_timeout 6m; +location /bar/ +@{ +proxy_pass https://gnunet.foo.org:4433/; +proxy_buffering off; +proxy_connect_timeout 5; # more than http_server +proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout +proxy_http_version 1.1; # 1.0 default +proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; +@} +@end example + +@node Reverse Proxy - Configure your GNUnet peer +@subsubsection Reverse Proxy - Configure your GNUnet peer + +To have your GNUnet peer announce the address, you have to specify the +@code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} +section: + +@example +[transport-http_server] +EXTERNAL_HOSTNAME = http://www.foo.org/bar/ +@end example + +@noindent +and/or @code{[transport-https_server]} section: + +@example +[transport-https_server] +EXTERNAL_HOSTNAME = https://www.foo.org/bar/ +@end example + +@noindent +Now restart your webserver and your peer... + +@node Blacklisting peers +@subsection Blacklisting peers + +Transport service supports to deny connecting to a specific peer of to a +specific peer with a specific transport plugin using te blacklisting +component of transport service. With@ blacklisting it is possible to deny +connections to specific peers of@ to use a specific plugin to a specific +peer. Peers can be blacklisted using@ the configuration or a blacklist +client can be asked. + +To blacklist peers using the configuration you have to add a section to +your configuration containing the peer id of the peer to blacklist and +the plugin@ if required. + +Examples: + +To blacklist connections to P565... on peer AG2P... using tcp add: + +@c FIXME: This is too long and produces errors in the pdf. +@example +[transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp +@end example + +To blacklist connections to P565... on peer AG2P... using all plugins add: + +@example +[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = +@end example + +You can also add a blacklist client usign the blacklist API. On a +blacklist check, blacklisting first checks internally if the peer is +blacklisted and if not, it asks the blacklisting clients. Clients are +asked if it is OK to connect to a peer ID, the plugin is omitted. + +On blacklist check for (peer, plugin) +@itemize @bullet +@item Do we have a local blacklist entry for this peer and this plugin?@ +@item YES: disallow connection@ +@item Do we have a local blacklist entry for this peer and all plugins?@ +@item YES: disallow connection@ +@item Does one of the clients disallow?@ +@item YES: disallow connection +@end itemize + +@node Configuration of the HTTP and HTTPS transport plugins +@subsection Configuration of the HTTP and HTTPS transport plugins + +The client parts of the http and https transport plugins can be configured +to use a proxy to connect to the hostlist server. This functionality can +be configured in the configuration file directly or using the +gnunet-setup tool. + +Both the HTTP and HTTPS clients support the following proxy types at +the moment: + +@itemize @bullet +@item HTTP 1.1 proxy +@item SOCKS 4/4a/5/5 with hostname +@end itemize + +In addition authentication at the proxy with username and password can be +configured. + +To configure proxy support for the clients in the gnunet-setup tool, +select the "transport" tab and activate the respective plugin. Now you +can select the appropriate proxy type. The hostname or IP address +(including port if required) has to be entered in the "Proxy hostname" +textbox. If required, enter username and password in the "Proxy username" +and "Proxy password" boxes. Be aware that these information will be stored +in the configuration in plain text. + +To configure these options directly in the configuration, you can +configure the following settings in the @code{[transport-http_client]} +and @code{[transport-https_client]} section of the configuration: + +@example +# Type of proxy server, +# Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME +# Default: HTTP +# PROXY_TYPE = HTTP + +# Hostname or IP of proxy server +# PROXY = +# User name for proxy server +# PROXY_USERNAME = +# User password for proxy server +# PROXY_PASSWORD = +@end example + +@node Configuring the GNU Name System +@subsection Configuring the GNU Name System + +@menu +* Configuring system-wide DNS interception:: +* Configuring the GNS nsswitch plugin:: +* Configuring GNS on W32:: +* GNS Proxy Setup:: +* Setup of the GNS CA:: +* Testing the GNS setup:: +@end menu + + +@node Configuring system-wide DNS interception +@subsubsection Configuring system-wide DNS interception + +Before you install GNUnet, make sure you have a user and group 'gnunet' +as well as an empty group 'gnunetdns'. + +When using GNUnet with system-wide DNS interception, it is absolutely +necessary for all GNUnet service processes to be started by +@code{gnunet-service-arm} as user and group 'gnunet'. You also need to be +sure to run @code{make install} as root (or use the @code{sudo} option to +configure) to grant GNUnet sufficient privileges. + +With this setup, all that is required for enabling system-wide DNS +interception is for some GNUnet component (VPN or GNS) to request it. +The @code{gnunet-service-dns} will then start helper programs that will +make the necessary changes to your firewall (@code{iptables}) rules. + +Note that this will NOT work if your system sends out DNS traffic to a +link-local IPv6 address, as in this case GNUnet can intercept the traffic, +but not inject the responses from the link-local IPv6 address. Hence you +cannot use system-wide DNS interception in conjunction with link-local +IPv6-based DNS servers. If such a DNS server is used, it will bypass +GNUnet's DNS traffic interception. + +Using the GNU Name System (GNS) requires two different configuration +steps. +First of all, GNS needs to be integrated with the operating system. Most +of this section is about the operating system level integration. + +The remainder of this chapter will detail the various methods for +configuring the use of GNS with your operating system. + +At this point in time you have different options depending on your OS: + +@table @asis + +@item Use the gnunet-gns-proxy This approach works for all operating +systems and is likely the easiest. However, it enables GNS only for +browsers, not for other applications that might be using DNS, such as SSH. +Still, using the proxy is required for using HTTP with GNS and is thus +recommended for all users. To do this, you simply have to run the +@code{gnunet-gns-proxy-setup-ca} script as the user who will run the +browser (this will create a GNS certificate authority (CA) on your system +and import its key into your browser), then start @code{gnunet-gns-proxy} +and inform your browser to use the Socks5 proxy which +@code{gnunet-gns-proxy} makes available by default on port 7777. +@item Use a nsswitch plugin (recommended on GNU systems) +This approach has the advantage of offering fully personalized resolution +even on multi-user systems. A potential disadvantage is that some +applications might be able to bypass GNS. +@item Use a W32 resolver plugin (recommended on W32) +This is currently the only option on W32 systems. +@item Use system-wide DNS packet interception +This approach is recommended for the GNUnet VPN. It can be used to handle +GNS at the same time; however, if you only use this method, you will only +get one root zone per machine (not so great for multi-user systems). +@end table + +You can combine system-wide DNS packet interception with the nsswitch +plugin. +The setup of the system-wide DNS interception is described here. All of +the other GNS-specific configuration steps are described in the following +sections. + +@node Configuring the GNS nsswitch plugin +@subsubsection Configuring the GNS nsswitch plugin + +The Name Service Switch (NSS) is a facility in Unix-like operating systems +@footnote{More accurate: NSS is a functionality of the GNU C Library} +that provides a variety of sources for common configuration databases and +name resolution mechanisms. +A superuser (system administrator) usually configures the +operating system's name services using the file +@file{/etc/nsswitch.conf}. + +GNS provides a NSS plugin to integrate GNS name resolution with the +operating system's name resolution process. +To use the GNS NSS plugin you have to either + +@itemize @bullet +@item install GNUnet as root or +@item compile GNUnet with the @code{--with-sudo=yes} switch. +@end itemize + +Name resolution is controlled by the @emph{hosts} section in the NSS +configuration. By default this section first performs a lookup in the +@file{/etc/hosts} file and then in DNS. +The nsswitch file should contain a line similar to: + +@example +hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 +@end example + +@noindent +Here the GNS NSS plugin can be added to perform a GNS lookup before +performing a DNS lookup. +The GNS NSS plugin has to be added to the "hosts" section in +@file{/etc/nsswitch.conf} file before DNS related plugins: + +@example +... +hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 +... +@end example + +@noindent +The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not +found in GNS it will not be queried in DNS. + +@node Configuring GNS on W32 +@subsubsection Configuring GNS on W32 + +This document is a guide to configuring GNU Name System on W32-compatible +platforms. + +After GNUnet is installed, run the w32nsp-install tool: + +@example +w32nsp-install.exe libw32nsp-0.dll +@end example + +@noindent +('0' is the library version of W32 NSP; it might increase in the future, +change the invocation accordingly). + +This will install GNS namespace provider into the system and allow other +applications to resolve names that end in '@strong{gnu}' +and '@strong{zkey}'. Note that namespace provider requires +gnunet-gns-helper-service-w32 to be running, as well as gns service +itself (and its usual dependencies). + +Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, +and this is where gnunet-gns-helper-service-w32 should be listening to +(and is configured to listen to by default). + +To uninstall the provider, run: + +@example +w32nsp-uninstall.exe +@end example + +@noindent +(uses provider GUID to uninstall it, does not need a dll name). + +Note that while MSDN claims that other applications will only be able to +use the new namespace provider after re-starting, in reality they might +stat to use it without that. Conversely, they might stop using the +provider after it's been uninstalled, even if they were not re-started. +W32 will not permit namespace provider library to be deleted or +overwritten while the provider is installed, and while there is at least +one process still using it (even after it was uninstalled). + +@node GNS Proxy Setup +@subsubsection GNS Proxy Setup + +When using the GNU Name System (GNS) to browse the WWW, there are several +issues that can be solved by adding the GNS Proxy to your setup: + +@itemize @bullet + +@item If the target website does not support GNS, it might assume that it +is operating under some name in the legacy DNS system (such as +example.com). It may then attempt to set cookies for that domain, and the +web server might expect a @code{Host: example.com} header in the request +from your browser. +However, your browser might be using @code{example.gnu} for the +@code{Host} header and might only accept (and send) cookies for +@code{example.gnu}. The GNS Proxy will perform the necessary translations +of the hostnames for cookies and HTTP headers (using the LEHO record for +the target domain as the desired substitute). + +@item If using HTTPS, the target site might include an SSL certificate +which is either only valid for the LEHO domain or might match a TLSA +record in GNS. However, your browser would expect a valid certificate for +@code{example.gnu}, not for some legacy domain name. The proxy will +validate the certificate (either against LEHO or TLSA) and then +on-the-fly produce a valid certificate for the exchange, signed by your +own CA. Assuming you installed the CA of your proxy in your browser's +certificate authority list, your browser will then trust the +HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. + +@item Finally, the proxy will in the future indicate to the server that it +speaks GNS, which will enable server operators to deliver GNS-enabled web +sites to your browser (and continue to deliver legacy links to legacy +browsers) +@end itemize + +@node Setup of the GNS CA +@subsubsection Setup of the GNS CA + +First you need to create a CA certificate that the proxy can use. +To do so use the provided script gnunet-gns-proxy-ca: + +@example +$ gnunet-gns-proxy-setup-ca +@end example + +@noindent +This will create a personal certification authority for you and add this +authority to the firefox and chrome database. The proxy will use the this +CA certificate to generate @code{*.gnu} client certificates on the fly. + +Note that the proxy uses libcurl. Make sure your version of libcurl uses +GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled +against OpenSSL. + +You can check the configuration your libcurl was build with by +running: + +@example +curl --version +@end example + +the output will look like this (without the linebreaks): + +@example +gnurl --version +curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ +GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 +Release-Date: 2017-10-08 +Protocols: http https +Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ +TLS-SRP UnixSockets HTTPS-proxy +@end example + +@node Testing the GNS setup +@subsubsection Testing the GNS setup + +Now for testing purposes we can create some records in our zone to test +the SSL functionality of the proxy: + +@example +$ gnunet-identity -C test +$ gnunet-namestore -a -e "1 d" -n "homepage" \ + -t A -V 131.159.74.67 -z test +$ gnunet-namestore -a -e "1 d" -n "homepage" \ + -t LEHO -V "gnunet.org" -z test +@end example + +@noindent +At this point we can start the proxy. Simply execute + +@example +$ gnunet-gns-proxy +@end example + +@noindent +Configure your browser to use this SOCKSv5 proxy on port 7777 and visit +this link. +If you use @command{Firefox} (or one of its derivatives/forks such as +Icecat) you also have to go to @code{about:config} and set the key +@code{network.proxy.socks_remote_dns} to @code{true}. + +When you visit @code{https://homepage.test/}, you should get to the +@code{https://gnunet.org/} frontpage and the browser (with the correctly +configured proxy) should give you a valid SSL certificate for +@code{homepage.gnu} and no warnings. It should look like this: + +@c FIXME: Image does not exist, create it or save it from Drupal? +@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} + + +@node Configuring the GNUnet VPN +@subsection Configuring the GNUnet VPN + +@menu +* IPv4 address for interface:: +* IPv6 address for interface:: +* Configuring the GNUnet VPN DNS:: +* Configuring the GNUnet VPN Exit Service:: +* IP Address of external DNS resolver:: +* IPv4 address for Exit interface:: +* IPv6 address for Exit interface:: +@end menu + +Before configuring the GNUnet VPN, please make sure that system-wide DNS +interception is configured properly as described in the section on the +GNUnet DNS setup. @pxref{Configuring the GNU Name System}, +if you haven't done so already. + +The default options for the GNUnet VPN are usually sufficient to use +GNUnet as a Layer 2 for your Internet connection. +However, what you always have to specify is which IP protocol you want +to tunnel: IPv4, IPv6 or both. +Furthermore, if you tunnel both, you most likely should also tunnel +all of your DNS requests. +You theoretically can tunnel "only" your DNS traffic, but that usually +makes little sense. + +The other options as shown on the gnunet-setup tool are: + +@node IPv4 address for interface +@subsubsection IPv4 address for interface + +This is the IPv4 address the VPN interface will get. You should pick an +'private' IPv4 network that is not yet in use for you system. For example, +if you use @code{10.0.0.1/255.255.0.0} already, you might use +@code{10.1.0.1/255.255.0.0}. +If you use @code{10.0.0.1/255.0.0.0} already, then you might use +@code{192.168.0.1/255.255.0.0}. +If your system is not in a private IP-network, using any of the above will +work fine. +You should try to make the mask of the address big enough +(@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more +mappings of remote IP Addresses into this range. +However, even a @code{255.255.255.0} mask will suffice for most users. + +@node IPv6 address for interface +@subsubsection IPv6 address for interface + +The IPv6 address the VPN interface will get. Here you can specify any +non-link-local address (the address should not begin with @code{fe80:}). +A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are +currently not using would be a good choice. + +@node Configuring the GNUnet VPN DNS +@subsubsection Configuring the GNUnet VPN DNS + +To resolve names for remote nodes, activate the DNS exit option. + +@node Configuring the GNUnet VPN Exit Service +@subsubsection Configuring the GNUnet VPN Exit Service + +If you want to allow other users to share your Internet connection (yes, +this may be dangerous, just as running a Tor exit node) or want to +provide access to services on your host (this should be less dangerous, +as long as those services are secure), you have to enable the GNUnet exit +daemon. + +You then get to specify which exit functions you want to provide. By +enabling the exit daemon, you will always automatically provide exit +functions for manually configured local services (this component of the +system is under +development and not documented further at this time). As for those +services you explicitly specify the target IP address and port, there is +no significant security risk in doing so. + +Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. +Being a DNS exit is usually pretty harmless. However, enabling IPv4 or +IPv6-exit without further precautions may enable adversaries to access +your local network, send spam, attack other systems from your Internet +connection and to other mischief that will appear to come from your +machine. This may or may not get you into legal trouble. +If you want to allow IPv4 or IPv6-exit functionality, you should strongly +consider adding additional firewall rules manually to protect your local +network and to restrict outgoing TCP traffic (i.e. by not allowing access +to port 25). While we plan to improve exit-filtering in the future, +you're currently on your own here. +Essentially, be prepared for any kind of IP-traffic to exit the respective +TUN interface (and GNUnet will enable IP-forwarding and NAT for the +interface automatically). + +Additional configuration options of the exit as shown by the gnunet-setup +tool are: + +@node IP Address of external DNS resolver +@subsubsection IP Address of external DNS resolver + +If DNS traffic is to exit your machine, it will be send to this DNS +resolver. You can specify an IPv4 or IPv6 address. + +@node IPv4 address for Exit interface +@subsubsection IPv4 address for Exit interface + +This is the IPv4 address the Interface will get. Make the mask of the +address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more +mappings of IP addresses into this range. As for the VPN interface, any +unused, private IPv4 address range will do. + +@node IPv6 address for Exit interface +@subsubsection IPv6 address for Exit interface + +The public IPv6 address the interface will get. If your kernel is not a +very recent kernel and you are willing to manually enable IPv6-NAT, the +IPv6 address you specify here must be a globally routed IPv6 address of +your host. + +Suppose your host has the address @code{2001:4ca0::1234/64}, then +using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, +then change at least one bit in the range before the bitmask, in the +example above we changed bit 111 from 0 to 1). + +You may also have to configure your router to route traffic for the entire +subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this +should be automatic with IPv6, but obviously anything can be +disabled). + +@node Bandwidth Configuration +@subsection Bandwidth Configuration + +You can specify how many bandwidth GNUnet is allowed to use to receive +and send data. This is important for users with limited bandwidth or +traffic volume. + +@node Configuring NAT +@subsection Configuring NAT + +Most hosts today do not have a normal global IP address but instead are +behind a router performing Network Address Translation (NAT) which assigns +each host in the local network a private IP address. +As a result, these machines cannot trivially receive inbound connections +from the Internet. GNUnet supports NAT traversal to enable these machines +to receive incoming connections from other peers despite their +limitations. + +In an ideal world, you can press the "Attempt automatic configuration" +button in gnunet-setup to automatically configure your peer correctly. +Alternatively, your distribution might have already triggered this +automatic configuration during the installation process. +However, automatic configuration can fail to determine the optimal +settings, resulting in your peer either not receiving as many connections +as possible, or in the worst case it not connecting to the network at all. + +To manually configure the peer, you need to know a few things about your +network setup. First, determine if you are behind a NAT in the first +place. +This is always the case if your IP address starts with "10.*" or +"192.168.*". Next, if you have control over your NAT router, you may +choose to manually configure it to allow GNUnet traffic to your host. +If you have configured your NAT to forward traffic on ports 2086 (and +possibly 1080) to your host, you can check the "NAT ports have been opened +manually" option, which corresponds to the "PUNCHED_NAT" option in the +configuration file. If you did not punch your NAT box, it may still be +configured to support UPnP, which allows GNUnet to automatically +configure it. In that case, you need to install the "upnpc" command, +enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal +via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the +configuration file). + +Some NAT boxes can be traversed using the autonomous NAT traversal method. +This requires certain GNUnet components to be installed with "SUID" +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. + + +@node Peer configuration for distributions +@subsection Peer configuration for distributions + +The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be +manually set to "/var/lib/gnunet/data/" as the default +"~/.local/share/gnunet/" is probably not that appropriate in this case. +Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to +"/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a +distribution decide to override system defaults, all of these changes +should be done in a custom @file{/etc/gnunet.conf} and not in the files +in the @file{config.d/} directory. + +Given the proposed access permissions, the "gnunet-setup" tool must be +run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it +modifies the system configuration). As always, gnunet-setup should be run +after the GNUnet peer was stopped using "gnunet-arm -e". Distributions +might want to include a wrapper for gnunet-setup that allows the +desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account +and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in +sequence. + +@node MOVED FROM USER Config Leftovers +@section MOVED FROM USER Config Leftovers + +This section describes how to start a GNUnet peer. It assumes that you +have already compiled and installed GNUnet and its' dependencies. +Before you start a GNUnet peer, you may want to create a configuration +file using gnunet-setup (but you do not have to). +Sane defaults should exist in your +@file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice +you could simply start without any configuration. If you want to +configure your peer later, you need to stop it before invoking the +@code{gnunet-setup} tool to customize further and to test your +configuration (@code{gnunet-setup} has build-in test functions). + +The most important option you might have to still set by hand is in +[PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where +GNUnet should store its data. +It defaults to @code{$HOME/}, which again should work for most users. +Make sure that the directory specified as GNUNET_HOME is writable to +the user that you will use to run GNUnet (note that you can run frontends +using other users, GNUNET_HOME must only be accessible to the user used to +run the background processes). + +You will also need to make one central decision: should all of GNUnet be +run under your normal UID, or do you want distinguish between system-wide +(user-independent) GNUnet services and personal GNUnet services. The +multi-user setup is slightly more complicated, but also more secure and +generally recommended. + +@menu +* The Single-User Setup:: +* The Multi-User Setup:: +* Killing GNUnet services:: +* Access Control for GNUnet:: +@end menu + +@node The Single-User Setup +@subsection The Single-User Setup + +For the single-user setup, you do not need to do anything special and can +just start the GNUnet background processes using @code{gnunet-arm}. +By default, GNUnet looks in @file{~/.config/gnunet.conf} for a +configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ +@code{$XDG_CONFIG_HOME} is defined). If your configuration lives +elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet +commands. + +Assuming the configuration file is called @file{~/.config/gnunet.conf}, +you start your peer using the @code{gnunet-arm} command (say as user +@code{gnunet}) using: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +@noindent +The "-s" option here is for "start". The command should return almost +instantly. If you want to stop GNUnet, you can use: + +@example +gnunet-arm -c ~/.config/gnunet.conf -e +@end example + +@noindent +The "-e" option here is for "end". + +Note that this will only start the basic peer, no actual applications +will be available. +If you want to start the file-sharing service, use (after starting +GNUnet): + +@example +gnunet-arm -c ~/.config/gnunet.conf -i fs +@end example + +@noindent +The "-i fs" option here is for "initialize" the "fs" (file-sharing) +application. You can also selectively kill only file-sharing support using + +@example +gnunet-arm -c ~/.config/gnunet.conf -k fs +@end example + +@noindent +Assuming that you want certain services (like file-sharing) to be always +automatically started whenever you start GNUnet, you can activate them by +setting "IMMEDIATE_START=YES" in the respective section of the configuration +file (for example, "[fs]"). Then GNUnet with file-sharing support would +be started whenever you@ enter: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +@noindent +Alternatively, you can combine the two options: + +@example +gnunet-arm -c ~/.config/gnunet.conf -s -i fs +@end example + +@noindent +Using @code{gnunet-arm} is also the preferred method for initializing +GNUnet from @code{init}. + +Finally, you should edit your @code{crontab} (using the @code{crontab} +command) and insert a line@ + +@example +@@reboot gnunet-arm -c ~/.config/gnunet.conf -s +@end example + +to automatically start your peer whenever your system boots. + +@node The Multi-User Setup +@subsection The Multi-User Setup + +This requires you to create a user @code{gnunet} and an additional group +@code{gnunetdns}, prior to running @code{make install} during +installation. +Then, you create a configuration file @file{/etc/gnunet.conf} which should +contain the lines:@ + +@example +[arm] +START_SYSTEM_SERVICES = YES +START_USER_SERVICES = NO +@end example + +@noindent +Then, perform the same steps to run GNUnet as in the per-user +configuration, except as user @code{gnunet} (including the +@code{crontab} installation). +You may also want to run @code{gnunet-setup} to configure your peer +(databases, etc.). +Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you +run @code{gnunet-setup} as user @code{gnunet}, you might need to change +permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can +write to the file (during setup). + +Afterwards, you need to perform another setup step for each normal user +account from which you want to access GNUnet. First, grant the normal user +(@code{$USER}) permission to the group gnunet: + +@example +# adduser $USER gnunet +@end example + +@noindent +Then, create a configuration file in @file{~/.config/gnunet.conf} for the +$USER with the lines: + +@example +[arm] +START_SYSTEM_SERVICES = NO +START_USER_SERVICES = YES +@end example + +@noindent +This will ensure that @code{gnunet-arm} when started by the normal user +will only run services that are per-user, and otherwise rely on the +system-wide services. +Note that the normal user may run gnunet-setup, but the +configuration would be ineffective as the system-wide services will use +@file{/etc/gnunet.conf} and ignore options set by individual users. + +Again, each user should then start the peer using +@file{gnunet-arm -s} --- and strongly consider adding logic to start +the peer automatically to their crontab. + +Afterwards, you should see two (or more, if you have more than one USER) +@code{gnunet-service-arm} processes running in your system. + +@node Killing GNUnet services +@subsection Killing GNUnet services + +It is not necessary to stop GNUnet services explicitly when shutting +down your computer. + +It should be noted that manually killing "most" of the +@code{gnunet-service} processes is generally not a successful method for +stopping a peer (since @code{gnunet-service-arm} will instantly restart +them). The best way to explicitly stop a peer is using +@code{gnunet-arm -e}; note that the per-user services may need to be +terminated before the system-wide services will terminate normally. + +@node Access Control for GNUnet +@subsection Access Control for GNUnet + +This chapter documents how we plan to make access control work within the +GNUnet system for a typical peer. It should be read as a best-practice +installation guide for advanced users and builders of binary +distributions. The recommendations in this guide apply to POSIX-systems +with full support for UNIX domain sockets only. + +Note that this is an advanced topic. The discussion presumes a very good +understanding of users, groups and file permissions. Normal users on +hosts with just a single user can just install GNUnet under their own +account (and possibly allow the installer to use SUDO to grant additional +permissions for special GNUnet tools that need additional rights). +The discussion below largely applies to installations where multiple users +share a system and to installations where the best possible security is +paramount. + +A typical GNUnet system consists of components that fall into four +categories: + +@table @asis + +@item User interfaces +User interfaces are not security sensitive and are supposed to be run and +used by normal system users. +The GTK GUIs and most command-line programs fall into this category. +Some command-line tools (like gnunet-transport) should be excluded as they +offer low-level access that normal users should not need. +@item System services and support tools +System services should always run and offer services that can then be +accessed by the normal users. +System services do not require special permissions, but as they are not +specific to a particular user, they probably should not run as a +particular user. Also, there should typically only be one GNUnet peer per +host. System services include the gnunet-service and gnunet-daemon +programs; support tools include command-line programs such as gnunet-arm. +@item Privileged helpers +Some GNUnet components require root rights to open raw sockets or perform +other special operations. These gnunet-helper binaries are typically +installed SUID and run from services or daemons. +@item Critical services +Some GNUnet services (such as the DNS service) can manipulate the service +in deep and possibly highly security sensitive ways. For example, the DNS +service can be used to intercept and alter any DNS query originating from +the local machine. Access to the APIs of these critical services and their +privileged helpers must be tightly controlled. +@end table + +@c FIXME: The titles of these chapters are too long in the index. + +@menu +* Recommendation - Disable access to services via TCP:: +* Recommendation - Run most services as system user "gnunet":: +* Recommendation - Control access to services using group "gnunet":: +* Recommendation - Limit access to certain SUID binaries by group "gnunet":: +* Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: +* Differences between "make install" and these recommendations:: +@end menu + +@node Recommendation - Disable access to services via TCP +@subsubsection Recommendation - Disable access to services via TCP + +GNUnet services allow two types of access: via TCP socket or via UNIX +domain socket. +If the service is available via TCP, access control can only be +implemented by restricting connections to a particular range of IP +addresses. +This is acceptable for non-critical services that are supposed to be +available to all users on the local system or local network. +However, as TCP is generally less efficient and it is rarely the case +that a single GNUnet peer is supposed to serve an entire local network, +the default configuration should disable TCP access to all GNUnet +services on systems with support for UNIX domain sockets. +As of GNUnet 0.9.2, configuration files with TCP access disabled should be +generated by default. Users can re-enable TCP access to particular +services simply by specifying a non-zero port number in the section of +the respective service. + + +@node Recommendation - Run most services as system user "gnunet" +@subsubsection Recommendation - Run most services as system user "gnunet" + +GNUnet's main services should be run as a separate user "gnunet" in a +special group "gnunet". +The user "gnunet" should start the peer using "gnunet-arm -s" during +system startup. The home directory for this user should be +@file{/var/lib/gnunet} and the configuration file should be +@file{/etc/gnunet.conf}. +Only the @code{gnunet} user should have the right to access +@file{/var/lib/gnunet} (@emph{mode: 700}). + +@node Recommendation - Control access to services using group "gnunet" +@subsubsection Recommendation - Control access to services using group "gnunet" + +Users that should be allowed to use the GNUnet peer should be added to the +group "gnunet". Using GNUnet's access control mechanism for UNIX domain +sockets, those services that are considered useful to ordinary users +should be made available by setting "UNIX_MATCH_GID=YES" for those +services. +Again, as shipped, GNUnet provides reasonable defaults. +Permissions to access the transport and core subsystems might additionally +be granted without necessarily causing security concerns. +Some services, such as DNS, must NOT be made accessible to the "gnunet" +group (and should thus only be accessible to the "gnunet" user and +services running with this UID). + +@node Recommendation - Limit access to certain SUID binaries by group "gnunet" +@subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" + +Most of GNUnet's SUID binaries should be safe even if executed by normal +users. However, it is possible to reduce the risk a little bit more by +making these binaries owned by the group "gnunet" and restricting their +execution to user of the group "gnunet" as well (4750). + +@node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" +@subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" + +A special group "gnunetdns" should be created for controlling access to +the "gnunet-helper-dns". +The binary should then be owned by root and be in group "gnunetdns" and +be installed SUID and only be group-executable (2750). +@b{Note that the group "gnunetdns" should have no users in it at all, +ever.} +The "gnunet-service-dns" program should be executed by user "gnunet" (via +gnunet-service-arm) with the binary owned by the user "root" and the group +"gnunetdns" and be SGID (2700). This way, @strong{only} +"gnunet-service-dns" can change its group to "gnunetdns" and execute the +helper, and the helper can then run as root (as per SUID). +Access to the API offered by "gnunet-service-dns" is in turn restricted +to the user "gnunet" (not the group!), which means that only +"benign" services can manipulate DNS queries using "gnunet-service-dns". + +@node Differences between "make install" and these recommendations +@subsubsection Differences between "make install" and these recommendations + +The current build system does not set all permissions automatically based +on the recommendations above. In particular, it does not use the group +"gnunet" at all (so setting gnunet-helpers other than the +gnunet-helper-dns to be owned by group "gnunet" must be done manually). +Furthermore, 'make install' will silently fail to set the DNS binaries to +be owned by group "gnunetdns" unless that group already exists (!). +An alternative name for the "gnunetdns" group can be specified using the +@code{--with-gnunetdns=GRPNAME} configure option. + diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi index 3e65cdc0e..fe47abb86 100644 --- a/doc/documentation/chapters/user.texi +++ b/doc/documentation/chapters/user.texi @@ -27,9 +27,6 @@ always welcome. * File-sharing:: * The GNU Name System:: * Using the Virtual Public Network:: -* MOVE TO INSTALL The graphical configuration interface:: -* MOVE TO INSTALL Checking the Installation:: -* MOVE TO INSTALL Config Leftovers:: @end menu @node Start and stop GNUnet @@ -1957,2007 +1954,3 @@ protocol (--tcp or --udp) and you will again receive an IP address that will terminate at the respective peer's service. - -@c NOTE: Inserted from Installation Handbook in original ``order'': -@c FIXME: Move this to User Handbook. -@node MOVE TO INSTALL The graphical configuration interface -@section MOVE TO INSTALL The graphical configuration interface - -If you also would like to use @command{gnunet-gtk} and -@command{gnunet-setup} (highly recommended for beginners), do: - -@menu -* Configuring your peer:: -* Configuring the Friend-to-Friend (F2F) mode:: -* Configuring the hostlist to bootstrap:: -* Configuration of the HOSTLIST proxy settings:: -* Configuring your peer to provide a hostlist :: -* Configuring the datastore:: -* Configuring the MySQL database:: -* Reasons for using MySQL:: -* Reasons for not using MySQL:: -* Setup Instructions:: -* Testing:: -* Performance Tuning:: -* Setup for running Testcases:: -* Configuring the Postgres database:: -* Reasons to use Postgres:: -* Reasons not to use Postgres:: -* Manual setup instructions:: -* Testing the setup manually:: -* Configuring the datacache:: -* Configuring the file-sharing service:: -* Configuring logging:: -* Configuring the transport service and plugins:: -* Configuring the WLAN transport plugin:: -* Configuring HTTP(S) reverse proxy functionality using Apache or nginx:: -* Blacklisting peers:: -* Configuration of the HTTP and HTTPS transport plugins:: -* Configuring the GNU Name System:: -* Configuring the GNUnet VPN:: -* Bandwidth Configuration:: -* Configuring NAT:: -* Peer configuration for distributions:: -@end menu - -@node Configuring your peer -@subsection Configuring your peer - -This chapter will describe the various configuration options in GNUnet. - -The easiest way to configure your peer is to use the -@command{gnunet-setup} tool. -@command{gnunet-setup} is part of the @command{gnunet-gtk} -application. You might have to install it separately. - -Many of the specific sections from this chapter actually are linked from -within @command{gnunet-setup} to help you while using the setup tool. - -While you can also configure your peer by editing the configuration -file by hand, this is not recommended for anyone except for developers -as it requires a more in-depth understanding of the configuration files -and internal dependencies of GNUnet. - -@node Configuring the Friend-to-Friend (F2F) mode -@subsection Configuring the Friend-to-Friend (F2F) mode - -GNUnet knows three basic modes of operation: -@itemize @bullet -@item In standard "peer-to-peer" mode, -your peer will connect to any peer. -@item In the pure "friend-to-friend" -mode, your peer will ONLY connect to peers from a list of friends -specified in the configuration. -@item Finally, in mixed mode, -GNUnet will only connect to arbitrary peers if it -has at least a specified number of connections to friends. -@end itemize - -When configuring any of the F2F ("friend-to-friend") modes, -you first need to create a file with the peer identities -of your friends. Ask your friends to run - -@example -$ gnunet-peerinfo -sq -@end example - -@noindent -The resulting output of this command needs to be added to your -@file{friends} file, which is simply a plain text file with one line -per friend with the output from the above command. - -You then specify the location of your @file{friends} file in the -@code{FRIENDS} option of the "topology" section. - -Once you have created the @file{friends} file, you can tell GNUnet to only -connect to your friends by setting the @code{FRIENDS-ONLY} option -(again in the "topology" section) to YES. - -If you want to run in mixed-mode, set "FRIENDS-ONLY" to NO and configure a -minimum number of friends to have (before connecting to arbitrary peers) -under the "MINIMUM-FRIENDS" option. - -If you want to operate in normal P2P-only mode, simply set -@code{MINIMUM-FRIENDS} to zero and @code{FRIENDS_ONLY} to NO. -This is the default. - -@node Configuring the hostlist to bootstrap -@subsection Configuring the hostlist to bootstrap - -After installing the software you need to get connected to the GNUnet -network. The configuration file included in your download is already -configured to connect you to the GNUnet network. -In this section the relevant configuration settings are explained. - -To get an initial connection to the GNUnet network and to get to know -peers already connected to the network you can use the so called -"bootstrap servers". -These servers can give you a list of peers connected to the network. -To use these bootstrap servers you have to configure the hostlist daemon -to activate bootstrapping. - -To activate bootstrapping, edit the @code{[hostlist]}-section in your -configuration file. You have to set the argument @command{-b} in the -options line: - -@example -[hostlist] -OPTIONS = -b -@end example - -Additionally you have to specify which server you want to use. -The default bootstrapping server is -"@uref{http://v10.gnunet.org/hostlist, http://v10.gnunet.org/hostlist}". -[^] To set the server you have to edit the line "SERVERS" in the hostlist -section. To use the default server you should set the lines to - -@example -SERVERS = http://v10.gnunet.org/hostlist [^] -@end example - -@noindent -To use bootstrapping your configuration file should include these lines: - -@example -[hostlist] -OPTIONS = -b -SERVERS = http://v10.gnunet.org/hostlist [^] -@end example - -@noindent -Besides using bootstrap servers you can configure your GNUnet peer to -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 @command{-e} -switch to the @code{OPTIONS} line in the hostlist section: - -@example -[hostlist] -OPTIONS = -b -e -@end example - -@noindent -Furthermore you can specify in which file the lists are saved. -To save the lists in the file @file{hostlists.file} just add the line: - -@example -HOSTLISTFILE = hostlists.file -@end example - -@noindent -Best practice is to activate both bootstrapping and hostlist learning. -So your configuration file should include these lines: - -@example -[hostlist] -OPTIONS = -b -e -HTTPPORT = 8080 -SERVERS = http://v10.gnunet.org/hostlist [^] -HOSTLISTFILE = $SERVICEHOME/hostlists.file -@end example - -@node Configuration of the HOSTLIST proxy settings -@subsection Configuration of the HOSTLIST proxy settings - -The hostlist client can be configured to use a proxy to connect to the -hostlist server. -This functionality can be configured in the configuration file directly -or using the @command{gnunet-setup} tool. - -The hostlist client supports the following proxy types at the moment: - -@itemize @bullet -@item HTTP and HTTP 1.0 only proxy -@item SOCKS 4/4a/5/5 with hostname -@end itemize - -In addition authentication at the proxy with username and password can be -configured. - -To configure proxy support for the hostlist client in the -@command{gnunet-setup} tool, select the "hostlist" tab and select -the appropriate proxy type. -The hostname or IP address (including port if required) has to be entered -in the "Proxy hostname" textbox. If required, enter username and password -in the "Proxy username" and "Proxy password" boxes. -Be aware that this information will be stored in the configuration in -plain text (TODO: Add explanation and generalize the part in Chapter 3.6 -about the encrypted home). - -To provide these options directly in the configuration, you can -enter the following settings in the @code{[hostlist]} section of -the configuration: - -@example -# Type of proxy server, -# Valid values: HTTP, HTTP_1_0, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME -# Default: HTTP -# PROXY_TYPE = HTTP - -# Hostname or IP of proxy server -# PROXY = -# User name for proxy server -# PROXY_USERNAME = -# User password for proxy server -# PROXY_PASSWORD = -@end example - -@node Configuring your peer to provide a hostlist -@subsection Configuring your peer to provide a hostlist - -If you operate a peer permanently connected to GNUnet you can configure -your peer to act as a hostlist server, providing other peers the list of -peers known to him. - -Your server can act as a bootstrap server and peers needing to obtain a -list of peers can contact it to download this list. -To download this hostlist the peer uses HTTP. -For this reason you have to build your peer with libgnurl (or libcurl) -and microhttpd support. - -To configure your peer to act as a bootstrap server you have to add the -@command{-p} option to @code{OPTIONS} in the @code{[hostlist]} section -of your configuration file. -Besides that you have to specify a port number for the http server. -In conclusion you have to add the following lines: - -@example -[hostlist] -HTTPPORT = 12980 -OPTIONS = -p -@end example - -@noindent -If your peer acts as a bootstrap server other peers should know about -that. You can advertise the hostlist your are providing to other peers. -Peers connecting to your peer will get a message containing an -advertisement for your hostlist and the URL where it can be downloaded. -If this peer is in learning mode, it will test the hostlist and, in the -case it can obtain the list successfully, it will save it for -bootstrapping. - -To activate hostlist advertisement on your peer, you have to set the -following lines in your configuration file: - -@example -[hostlist] -EXTERNAL_DNS_NAME = example.org -HTTPPORT = 12981 -OPTIONS = -p -a -@end example - -@noindent -With this configuration your peer will a act as a bootstrap server and -advertise this hostlist to other peers connecting to it. -The URL used to download the list will be -@code{@uref{http://example.org:12981/, http://example.org:12981/}}. - -Please notice: - -@itemize @bullet -@item The hostlist is @b{not} human readable, so you should not try to -download it using your webbrowser. Just point your GNUnet peer to the -address! -@item Advertising without providing a hostlist does not make sense and -will not work. -@end itemize - -@node Configuring the datastore -@subsection Configuring the datastore - -The datastore is what GNUnet uses for long-term storage of file-sharing -data. Note that long-term does not mean 'forever' since content does have -an expiration date, and of course storage space is finite (and hence -sometimes content may have to be discarded). - -Use the @code{QUOTA} option to specify how many bytes of storage space -you are willing to dedicate to GNUnet. - -In addition to specifying the maximum space GNUnet is allowed to use for -the datastore, you need to specify which database GNUnet should use to do -so. Currently, you have the choice between sqLite, MySQL and Postgres. - -@node Configuring the MySQL database -@subsection Configuring the MySQL database - -This section describes how to setup the MySQL database for GNUnet. - -Note that the mysql plugin does NOT work with mysql before 4.1 since we -need prepared statements. -We are generally testing the code against MySQL 5.1 at this point. - -@node Reasons for using MySQL -@subsection Reasons for using MySQL - -@itemize @bullet - -@item On up-to-date hardware wher -mysql can be used comfortably, this module -will have better performance than the other database choices (according -to our tests). - -@item Its often possible to recover the mysql database from internal -inconsistencies. Some of the other databases do not support repair. -@end itemize - -@node Reasons for not using MySQL -@subsection Reasons for not using MySQL - -@itemize @bullet -@item Memory usage (likely not an issue if you have more than 1 GB) -@item Complex manual setup -@end itemize - -@node Setup Instructions -@subsection Setup Instructions - -@itemize @bullet - -@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for -@code{DATABASE} to @code{mysql}. - -@item Access mysql as root: - -@example -$ mysql -u root -p -@end example - -@noindent -and issue the following commands, replacing $USER with the username -that will be running @command{gnunet-arm} (so typically "gnunet"): - -@example -CREATE DATABASE gnunet; -GRANT select,insert,update,delete,create,alter,drop,create \ -temporary tables ON gnunet.* TO $USER@@localhost; -SET PASSWORD FOR $USER@@localhost=PASSWORD('$the_password_you_like'); -FLUSH PRIVILEGES; -@end example - -@item -In the $HOME directory of $USER, create a @file{.my.cnf} file with the -following lines - -@example -[client] -user=$USER -password=$the_password_you_like -@end example - -@end itemize - -That's it. Note that @file{.my.cnf} file is a slight security risk unless -its on a safe partition. The @file{$HOME/.my.cnf} can of course be -a symbolic link. -Luckily $USER has only privileges to mess up GNUnet's tables, -which should be pretty harmless. - -@node Testing -@subsection Testing - -You should briefly try if the database connection works. First, login -as $USER. Then use: - -@example -$ mysql -u $USER -mysql> use gnunet; -@end example - -@noindent -If you get the message - -@example -Database changed -@end example - -@noindent -it probably works. - -If you get - -@example -ERROR 2002: Can't connect to local MySQL server -through socket '/tmp/mysql.sock' (2) -@end example - -@noindent -it may be resolvable by - -@example -ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock -@end example - -@noindent -so there may be some additional trouble depending on your mysql setup. - -@node Performance Tuning -@subsection Performance Tuning - -For GNUnet, you probably want to set the option - -@example -innodb_flush_log_at_trx_commit = 0 -@end example - -@noindent -for a rather dramatic boost in MySQL performance. However, this reduces -the "safety" of your database as with this options you may loose -transactions during a power outage. -While this is totally harmless for GNUnet, the option applies to all -applications using MySQL. So you should set it if (and only if) GNUnet is -the only application on your system using MySQL. - -@node Setup for running Testcases -@subsection Setup for running Testcases - -If you want to run the testcases, you must create a second database -"gnunetcheck" with the same username and password. This database will -then be used for testing (@command{make check}). - -@node Configuring the Postgres database -@subsection Configuring the Postgres database - -This text describes how to setup the Postgres database for GNUnet. - -This Postgres plugin was developed for Postgres 8.3 but might work for -earlier versions as well. - -@node Reasons to use Postgres -@subsection Reasons to use Postgres - -@itemize @bullet -@item Easier to setup than MySQL -@item Real database -@end itemize - -@node Reasons not to use Postgres -@subsection Reasons not to use Postgres - -@itemize @bullet -@item Quite slow -@item Still some manual setup required -@end itemize - -@node Manual setup instructions -@subsection Manual setup instructions - -@itemize @bullet -@item In @file{gnunet.conf} set in section @code{DATASTORE} the value for -@code{DATABASE} to @code{postgres}. -@item Access Postgres to create a user: - -@table @asis -@item with Postgres 8.x, use: - -@example -# su - postgres -$ createuser -@end example - -@noindent -and enter the name of the user running GNUnet for the role interactively. -Then, when prompted, do not set it to superuser, allow the creation of -databases, and do not allow the creation of new roles. - -@item with Postgres 9.x, use: - -@example -# su - postgres -$ createuser -d $GNUNET_USER -@end example - -@noindent -where $GNUNET_USER is the name of the user running GNUnet. - -@end table - - -@item -As that user (so typically as user "gnunet"), create a database (or two): - -@example -$ createdb gnunet -# this way you can run "make check" -$ createdb gnunetcheck -@end example - -@end itemize - -Now you should be able to start @code{gnunet-arm}. - -@node Testing the setup manually -@subsection Testing the setup manually - -You may want to try if the database connection works. First, again login -as the user who will run @command{gnunet-arm}. Then use: - -@example -$ psql gnunet # or gnunetcheck -gnunet=> \dt -@end example - -@noindent -If, after you have started @command{gnunet-arm} at least once, you get -a @code{gn090} table here, it probably works. - -@node Configuring the datacache -@subsection Configuring the datacache -@c %**end of header - -The datacache is what GNUnet uses for storing temporary data. This data is -expected to be wiped completely each time GNUnet is restarted (or the -system is rebooted). - -You need to specify how many bytes GNUnet is allowed to use for the -datacache using the @code{QUOTA} option in the section @code{[dhtcache]}. -Furthermore, you need to specify which database backend should be used to -store the data. Currently, you have the choice between -sqLite, MySQL and Postgres. - -@node Configuring the file-sharing service -@subsection Configuring the file-sharing service - -In order to use GNUnet for file-sharing, you first need to make sure -that the file-sharing service is loaded. -This is done by setting the @code{START_ON_DEMAND} option in -section @code{[fs]} to "YES". Alternatively, you can run - -@example -$ gnunet-arm -i fs -@end example - -@noindent -to start the file-sharing service by hand. - -Except for configuring the database and the datacache the only important -option for file-sharing is content migration. - -Content migration allows your peer to cache content from other peers as -well as send out content stored on your system without explicit requests. -This content replication has positive and negative impacts on both system -performance and privacy. - -FIXME: discuss the trade-offs. Here is some older text about it... - -Setting this option to YES allows gnunetd to migrate data to the local -machine. Setting this option to YES is highly recommended for efficiency. -Its also the default. If you set this value to YES, GNUnet will store -content on your machine that you cannot decrypt. -While this may protect you from liability if the judge is sane, it may -not (IANAL). If you put illegal content on your machine yourself, setting -this option to YES will probably increase your chances to get away with it -since you can plausibly deny that you inserted the content. -Note that in either case, your anonymity would have to be broken first -(which may be possible depending on the size of the GNUnet network and the -strength of the adversary). - -@node Configuring logging -@subsection Configuring logging - -Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. -Using @code{-L}, a log level can be specified. With log level -@code{ERROR} only serious errors are logged. -The default log level is @code{WARNING} which causes anything of -concern to be logged. -Log level @code{INFO} can be used to log anything that might be -interesting information whereas -@code{DEBUG} can be used by developers to log debugging messages -(but you need to run @code{./configure} with -@code{--enable-logging=verbose} to get them compiled). -The @code{-l} option is used to specify the log file. - -Since most GNUnet services are managed by @code{gnunet-arm}, using the -@code{-l} or @code{-L} options directly is not possible. -Instead, they can be specified using the @code{OPTIONS} configuration -value in the respective section for the respective service. -In order to enable logging globally without editing the @code{OPTIONS} -values for each service, @command{gnunet-arm} supports a -@code{GLOBAL_POSTFIX} option. -The value specified here is given as an extra option to all services for -which the configuration does contain a service-specific @code{OPTIONS} -field. - -@code{GLOBAL_POSTFIX} can contain the special sequence "@{@}" which -is replaced by the name of the service that is being started. -Furthermore, @code{GLOBAL_POSTFIX} is special in that sequences -starting with "$" anywhere in the string are expanded (according -to options in @code{PATHS}); this expansion otherwise is -only happening for filenames and then the "$" must be the -first character in the option. Both of these restrictions do -not apply to @code{GLOBAL_POSTFIX}. -Note that specifying @code{%} anywhere in the @code{GLOBAL_POSTFIX} -disables both of these features. - -In summary, in order to get all services to log at level -@code{INFO} to log-files called @code{SERVICENAME-logs}, the -following global prefix should be used: - -@example -GLOBAL_POSTFIX = -l $SERVICEHOME/@{@}-logs -L INFO -@end example - -@node Configuring the transport service and plugins -@subsection Configuring the transport service and plugins - -The transport service in GNUnet is responsible to maintain basic -connectivity to other peers. -Besides initiating and keeping connections alive it is also responsible -for address validation. - -The GNUnet transport supports more than one transport protocol. -These protocols are configured together with the transport service. - -The configuration section for the transport service itself is quite -similar to all the other services - -@example -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 -@end example - -Different are the settings for the plugins to load @code{PLUGINS}. -The first setting specifies which transport plugins to load. - -@itemize @bullet -@item transport-unix -A plugin for local only communication with UNIX domain sockets. Used for -testing and available on unix systems only. Just set the port - -@example -[transport-unix] -PORT = 22086 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@item transport-tcp -A plugin for communication with TCP. Set port to 0 for client mode with -outbound only connections - -@example -[transport-tcp] -# Use 0 to ONLY advertise as a peer behind NAT (no port binding) -PORT = 2086 -ADVERTISED_PORT = 2086 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -# Maximum number of open TCP connections allowed -MAX_CONNECTIONS = 128 -@end example - -@item transport-udp -A plugin for communication with UDP. Supports peer discovery using -broadcasts. - -@example -[transport-udp] -PORT = 2086 -BROADCAST = YES -BROADCAST_INTERVAL = 30 s -MAX_BPS = 1000000 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@item transport-http -HTTP and HTTPS support is split in two part: a client plugin initiating -outbound connections and a server part accepting connections from the -client. The client plugin just takes the maximum number of connections as -an argument. - -@example -[transport-http_client] -MAX_CONNECTIONS = 128 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@example -[transport-https_client] -MAX_CONNECTIONS = 128 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@noindent -The server has a port configured and the maximum 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 @code{EXTERNAL_HOSTNAME} setting. -The webserver under this address should forward the request to the peer -and the configure port. - -@example -[transport-http_server] -EXTERNAL_HOSTNAME = fulcrum.net.in.tum.de/gnunet -PORT = 1080 -MAX_CONNECTIONS = 128 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@example -[transport-https_server] -PORT = 4433 -CRYPTO_INIT = NORMAL -KEY_FILE = https.key -CERT_FILE = https.cert -MAX_CONNECTIONS = 128 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example - -@item transport-wlan - -The next section describes how to setup the WLAN plugin, -so here only the settings. Just specify the interface to use: - -@example -[transport-wlan] -# Name of the interface in monitor mode (typically monX) -INTERFACE = mon0 -# Real hardware, no testing -TESTMODE = 0 -TESTING_IGNORE_KEYS = ACCEPT_FROM; -@end example -@end itemize - -@node Configuring the WLAN transport plugin -@subsection Configuring the WLAN transport plugin - -The wlan transport plugin enables GNUnet to send and to receive data on a -wlan interface. -It has not to be connected to a wlan network as long as sender and -receiver are on the same channel. This enables you to get connection to -GNUnet where no internet access is possible, for example during -catastrophes or when censorship cuts you off from the internet. - - -@menu -* Requirements for the WLAN plugin:: -* Configuration:: -* Before starting GNUnet:: -* Limitations and known bugs:: -@end menu - - -@node Requirements for the WLAN plugin -@subsubsection Requirements for the WLAN plugin - -@itemize @bullet - -@item wlan network card with monitor support and packet injection -(see @uref{http://www.aircrack-ng.org/, aircrack-ng.org}) - -@item Linux kernel with mac80211 stack, introduced in 2.6.22, tested with -2.6.35 and 2.6.38 - -@item Wlantools to create the a monitor interface, tested with airmon-ng -of the aircrack-ng package -@end itemize - -@node Configuration -@subsubsection Configuration - -There are the following options for the wlan plugin (they should be like -this in your default config file, you only need to adjust them if the -values are incorrect for your system) - -@example -# section for the wlan transport plugin -[transport-wlan] -# interface to use, more information in the -# "Before starting GNUnet" section of the handbook. -INTERFACE = mon0 -# testmode for developers: -# 0 use wlan interface, -#1 or 2 use loopback driver for tests 1 = server, 2 = client -TESTMODE = 0 -@end example - -@node Before starting GNUnet -@subsubsection Before starting GNUnet - -Before starting GNUnet, you have to make sure that your wlan interface is -in monitor mode. -One way to put the wlan interface into monitor mode (if your interface -name is wlan0) is by executing: - -@example -sudo airmon-ng start wlan0 -@end example - -@noindent -Here is an example what the result should look like: - -@example -Interface Chipset Driver -wlan0 Intel 4965 a/b/g/n iwl4965 - [phy0] -(monitor mode enabled on mon0) -@end example - -@noindent -The monitor interface is mon0 is the one that you have to put into the -configuration file. - -@node Limitations and known bugs -@subsubsection Limitations and known bugs - -Wlan speed is at the maximum of 1 Mbit/s because support for choosing the -wlan speed with packet injection was removed in newer kernels. -Please pester the kernel developers about fixing this. - -The interface channel depends on the wlan network that the card is -connected to. If no connection has been made since the start of the -computer, it is usually the first channel of the card. -Peers will only find each other and communicate if they are on the same -channel. Channels must be set manually, i.e. using: - -@example -iwconfig wlan0 channel 1 -@end example - -@node Configuring HTTP(S) reverse proxy functionality using Apache or nginx -@subsection Configuring HTTP(S) reverse proxy functionality using Apache or nginx - -The HTTP plugin supports data transfer using reverse proxies. A reverse -proxy forwards the HTTP request he receives with a certain URL to another -webserver, here a GNUnet peer. - -So if you have a running Apache or nginx webserver you can configure it to -be a GNUnet reverse proxy. Especially if you have a well-known webiste -this improves censorship resistance since it looks as normal surfing -behaviour. - -To do so, you have to do two things: - -@itemize @bullet -@item Configure your webserver to forward the GNUnet HTTP traffic -@item Configure your GNUnet peer to announce the respective address -@end itemize - -As an example we want to use GNUnet peer running: - -@itemize @bullet - -@item HTTP server plugin on @code{gnunet.foo.org:1080} - -@item HTTPS server plugin on @code{gnunet.foo.org:4433} - -@item A apache or nginx webserver on -@uref{http://www.foo.org/, http://www.foo.org:80/} - -@item A apache or nginx webserver on https://www.foo.org:443/ -@end itemize - -And we want the webserver to accept GNUnet traffic under -@code{http://www.foo.org/bar/}. The required steps are described here: - -@menu -* Reverse Proxy - Configure your Apache2 HTTP webserver:: -* Reverse Proxy - Configure your Apache2 HTTPS webserver:: -* Reverse Proxy - Configure your nginx HTTPS webserver:: -* Reverse Proxy - Configure your nginx HTTP webserver:: -* Reverse Proxy - Configure your GNUnet peer:: -@end menu - -@node Reverse Proxy - Configure your Apache2 HTTP webserver -@subsubsection Reverse Proxy - Configure your Apache2 HTTP webserver - -First of all you need mod_proxy installed. - -Edit your webserver configuration. Edit -@code{/etc/apache2/apache2.conf} or the site-specific configuration file. - -In the respective @code{server config},@code{virtual host} or -@code{directory} section add the following lines: - -@example -ProxyTimeout 300 -ProxyRequests Off - -ProxyPass http://gnunet.foo.org:1080/ -ProxyPassReverse http://gnunet.foo.org:1080/ - -@end example - -@node Reverse Proxy - Configure your Apache2 HTTPS webserver -@subsubsection Reverse Proxy - Configure your Apache2 HTTPS webserver - -We assume that you already have an HTTPS server running, if not please -check how to configure a HTTPS host. An uncomplicated to use example -is the example configuration file for Apache2/HTTPD provided in -@file{apache2/sites-available/default-ssl}. - -In the respective HTTPS @code{server config},@code{virtual host} or -@code{directory} section add the following lines: - -@example -SSLProxyEngine On -ProxyTimeout 300 -ProxyRequests Off - -ProxyPass https://gnunet.foo.org:4433/ -ProxyPassReverse https://gnunet.foo.org:4433/ - -@end example - -@noindent -More information about the apache mod_proxy configuration can be found -in the Apache documentation@footnote{@uref{http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass, http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypass}} - -@node Reverse Proxy - Configure your nginx HTTPS webserver -@subsubsection Reverse Proxy - Configure your nginx HTTPS webserver - -Since nginx does not support chunked encoding, you first of all have to -install the @code{chunkin} module@footnote{@uref{http://wiki.nginx.org/HttpChunkinModule, http://wiki.nginx.org/HttpChunkinModule}} - -To enable chunkin add: - -@example -chunkin on; -error_page 411 = @@my_411_error; -location @@my_411_error @{ -chunkin_resume; -@} -@end example - -@noindent -Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or -the site-specific configuration file. - -In the @code{server} section add: - -@example -location /bar/ @{ -proxy_pass http://gnunet.foo.org:1080/; -proxy_buffering off; -proxy_connect_timeout 5; # more than http_server -proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout -proxy_http_version 1.1; # 1.0 default -proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; -@} -@end example - -@node Reverse Proxy - Configure your nginx HTTP webserver -@subsubsection Reverse Proxy - Configure your nginx HTTP webserver - -Edit your webserver configuration. Edit @file{/etc/nginx/nginx.conf} or -the site-specific configuration file. - -In the @code{server} section add: - -@example -ssl_session_timeout 6m; -location /bar/ -@{ -proxy_pass https://gnunet.foo.org:4433/; -proxy_buffering off; -proxy_connect_timeout 5; # more than http_server -proxy_read_timeout 350; # 60 default, 300s is GNUnet's idle timeout -proxy_http_version 1.1; # 1.0 default -proxy_next_upstream error timeout invalid_header http_500 http_503 http_502 http_504; -@} -@end example - -@node Reverse Proxy - Configure your GNUnet peer -@subsubsection Reverse Proxy - Configure your GNUnet peer - -To have your GNUnet peer announce the address, you have to specify the -@code{EXTERNAL_HOSTNAME} option in the @code{[transport-http_server]} -section: - -@example -[transport-http_server] -EXTERNAL_HOSTNAME = http://www.foo.org/bar/ -@end example - -@noindent -and/or @code{[transport-https_server]} section: - -@example -[transport-https_server] -EXTERNAL_HOSTNAME = https://www.foo.org/bar/ -@end example - -@noindent -Now restart your webserver and your peer... - -@node Blacklisting peers -@subsection Blacklisting peers - -Transport service supports to deny connecting to a specific peer of to a -specific peer with a specific transport plugin using te blacklisting -component of transport service. With@ blacklisting it is possible to deny -connections to specific peers of@ to use a specific plugin to a specific -peer. Peers can be blacklisted using@ the configuration or a blacklist -client can be asked. - -To blacklist peers using the configuration you have to add a section to -your configuration containing the peer id of the peer to blacklist and -the plugin@ if required. - -Examples: - -To blacklist connections to P565... on peer AG2P... using tcp add: - -@c FIXME: This is too long and produces errors in the pdf. -@example -[transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] -P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp -@end example - -To blacklist connections to P565... on peer AG2P... using all plugins add: - -@example -[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] -P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = -@end example - -You can also add a blacklist client usign the blacklist API. On a -blacklist check, blacklisting first checks internally if the peer is -blacklisted and if not, it asks the blacklisting clients. Clients are -asked if it is OK to connect to a peer ID, the plugin is omitted. - -On blacklist check for (peer, plugin) -@itemize @bullet -@item Do we have a local blacklist entry for this peer and this plugin?@ -@item YES: disallow connection@ -@item Do we have a local blacklist entry for this peer and all plugins?@ -@item YES: disallow connection@ -@item Does one of the clients disallow?@ -@item YES: disallow connection -@end itemize - -@node Configuration of the HTTP and HTTPS transport plugins -@subsection Configuration of the HTTP and HTTPS transport plugins - -The client parts of the http and https transport plugins can be configured -to use a proxy to connect to the hostlist server. This functionality can -be configured in the configuration file directly or using the -gnunet-setup tool. - -Both the HTTP and HTTPS clients support the following proxy types at -the moment: - -@itemize @bullet -@item HTTP 1.1 proxy -@item SOCKS 4/4a/5/5 with hostname -@end itemize - -In addition authentication at the proxy with username and password can be -configured. - -To configure proxy support for the clients in the gnunet-setup tool, -select the "transport" tab and activate the respective plugin. Now you -can select the appropriate proxy type. The hostname or IP address -(including port if required) has to be entered in the "Proxy hostname" -textbox. If required, enter username and password in the "Proxy username" -and "Proxy password" boxes. Be aware that these information will be stored -in the configuration in plain text. - -To configure these options directly in the configuration, you can -configure the following settings in the @code{[transport-http_client]} -and @code{[transport-https_client]} section of the configuration: - -@example -# Type of proxy server, -# Valid values: HTTP, SOCKS4, SOCKS5, SOCKS4A, SOCKS5_HOSTNAME -# Default: HTTP -# PROXY_TYPE = HTTP - -# Hostname or IP of proxy server -# PROXY = -# User name for proxy server -# PROXY_USERNAME = -# User password for proxy server -# PROXY_PASSWORD = -@end example - -@node Configuring the GNU Name System -@subsection Configuring the GNU Name System - -@menu -* Configuring system-wide DNS interception:: -* Configuring the GNS nsswitch plugin:: -* Configuring GNS on W32:: -* GNS Proxy Setup:: -* Setup of the GNS CA:: -* Testing the GNS setup:: -@end menu - - -@node Configuring system-wide DNS interception -@subsubsection Configuring system-wide DNS interception - -Before you install GNUnet, make sure you have a user and group 'gnunet' -as well as an empty group 'gnunetdns'. - -When using GNUnet with system-wide DNS interception, it is absolutely -necessary for all GNUnet service processes to be started by -@code{gnunet-service-arm} as user and group 'gnunet'. You also need to be -sure to run @code{make install} as root (or use the @code{sudo} option to -configure) to grant GNUnet sufficient privileges. - -With this setup, all that is required for enabling system-wide DNS -interception is for some GNUnet component (VPN or GNS) to request it. -The @code{gnunet-service-dns} will then start helper programs that will -make the necessary changes to your firewall (@code{iptables}) rules. - -Note that this will NOT work if your system sends out DNS traffic to a -link-local IPv6 address, as in this case GNUnet can intercept the traffic, -but not inject the responses from the link-local IPv6 address. Hence you -cannot use system-wide DNS interception in conjunction with link-local -IPv6-based DNS servers. If such a DNS server is used, it will bypass -GNUnet's DNS traffic interception. - -Using the GNU Name System (GNS) requires two different configuration -steps. -First of all, GNS needs to be integrated with the operating system. Most -of this section is about the operating system level integration. - -The remainder of this chapter will detail the various methods for -configuring the use of GNS with your operating system. - -At this point in time you have different options depending on your OS: - -@table @asis - -@item Use the gnunet-gns-proxy This approach works for all operating -systems and is likely the easiest. However, it enables GNS only for -browsers, not for other applications that might be using DNS, such as SSH. -Still, using the proxy is required for using HTTP with GNS and is thus -recommended for all users. To do this, you simply have to run the -@code{gnunet-gns-proxy-setup-ca} script as the user who will run the -browser (this will create a GNS certificate authority (CA) on your system -and import its key into your browser), then start @code{gnunet-gns-proxy} -and inform your browser to use the Socks5 proxy which -@code{gnunet-gns-proxy} makes available by default on port 7777. -@item Use a nsswitch plugin (recommended on GNU systems) -This approach has the advantage of offering fully personalized resolution -even on multi-user systems. A potential disadvantage is that some -applications might be able to bypass GNS. -@item Use a W32 resolver plugin (recommended on W32) -This is currently the only option on W32 systems. -@item Use system-wide DNS packet interception -This approach is recommended for the GNUnet VPN. It can be used to handle -GNS at the same time; however, if you only use this method, you will only -get one root zone per machine (not so great for multi-user systems). -@end table - -You can combine system-wide DNS packet interception with the nsswitch -plugin. -The setup of the system-wide DNS interception is described here. All of -the other GNS-specific configuration steps are described in the following -sections. - -@node Configuring the GNS nsswitch plugin -@subsubsection Configuring the GNS nsswitch plugin - -The Name Service Switch (NSS) is a facility in Unix-like operating systems -@footnote{More accurate: NSS is a functionality of the GNU C Library} -that provides a variety of sources for common configuration databases and -name resolution mechanisms. -A superuser (system administrator) usually configures the -operating system's name services using the file -@file{/etc/nsswitch.conf}. - -GNS provides a NSS plugin to integrate GNS name resolution with the -operating system's name resolution process. -To use the GNS NSS plugin you have to either - -@itemize @bullet -@item install GNUnet as root or -@item compile GNUnet with the @code{--with-sudo=yes} switch. -@end itemize - -Name resolution is controlled by the @emph{hosts} section in the NSS -configuration. By default this section first performs a lookup in the -@file{/etc/hosts} file and then in DNS. -The nsswitch file should contain a line similar to: - -@example -hosts: files dns [NOTFOUND=return] mdns4_minimal mdns4 -@end example - -@noindent -Here the GNS NSS plugin can be added to perform a GNS lookup before -performing a DNS lookup. -The GNS NSS plugin has to be added to the "hosts" section in -@file{/etc/nsswitch.conf} file before DNS related plugins: - -@example -... -hosts: files gns [NOTFOUND=return] dns mdns4_minimal mdns4 -... -@end example - -@noindent -The @code{NOTFOUND=return} will ensure that if a @code{.gnu} name is not -found in GNS it will not be queried in DNS. - -@node Configuring GNS on W32 -@subsubsection Configuring GNS on W32 - -This document is a guide to configuring GNU Name System on W32-compatible -platforms. - -After GNUnet is installed, run the w32nsp-install tool: - -@example -w32nsp-install.exe libw32nsp-0.dll -@end example - -@noindent -('0' is the library version of W32 NSP; it might increase in the future, -change the invocation accordingly). - -This will install GNS namespace provider into the system and allow other -applications to resolve names that end in '@strong{gnu}' -and '@strong{zkey}'. Note that namespace provider requires -gnunet-gns-helper-service-w32 to be running, as well as gns service -itself (and its usual dependencies). - -Namespace provider is hardcoded to connect to @strong{127.0.0.1:5353}, -and this is where gnunet-gns-helper-service-w32 should be listening to -(and is configured to listen to by default). - -To uninstall the provider, run: - -@example -w32nsp-uninstall.exe -@end example - -@noindent -(uses provider GUID to uninstall it, does not need a dll name). - -Note that while MSDN claims that other applications will only be able to -use the new namespace provider after re-starting, in reality they might -stat to use it without that. Conversely, they might stop using the -provider after it's been uninstalled, even if they were not re-started. -W32 will not permit namespace provider library to be deleted or -overwritten while the provider is installed, and while there is at least -one process still using it (even after it was uninstalled). - -@node GNS Proxy Setup -@subsubsection GNS Proxy Setup - -When using the GNU Name System (GNS) to browse the WWW, there are several -issues that can be solved by adding the GNS Proxy to your setup: - -@itemize @bullet - -@item If the target website does not support GNS, it might assume that it -is operating under some name in the legacy DNS system (such as -example.com). It may then attempt to set cookies for that domain, and the -web server might expect a @code{Host: example.com} header in the request -from your browser. -However, your browser might be using @code{example.gnu} for the -@code{Host} header and might only accept (and send) cookies for -@code{example.gnu}. The GNS Proxy will perform the necessary translations -of the hostnames for cookies and HTTP headers (using the LEHO record for -the target domain as the desired substitute). - -@item If using HTTPS, the target site might include an SSL certificate -which is either only valid for the LEHO domain or might match a TLSA -record in GNS. However, your browser would expect a valid certificate for -@code{example.gnu}, not for some legacy domain name. The proxy will -validate the certificate (either against LEHO or TLSA) and then -on-the-fly produce a valid certificate for the exchange, signed by your -own CA. Assuming you installed the CA of your proxy in your browser's -certificate authority list, your browser will then trust the -HTTPS/SSL/TLS connection, as the hostname mismatch is hidden by the proxy. - -@item Finally, the proxy will in the future indicate to the server that it -speaks GNS, which will enable server operators to deliver GNS-enabled web -sites to your browser (and continue to deliver legacy links to legacy -browsers) -@end itemize - -@node Setup of the GNS CA -@subsubsection Setup of the GNS CA - -First you need to create a CA certificate that the proxy can use. -To do so use the provided script gnunet-gns-proxy-ca: - -@example -$ gnunet-gns-proxy-setup-ca -@end example - -@noindent -This will create a personal certification authority for you and add this -authority to the firefox and chrome database. The proxy will use the this -CA certificate to generate @code{*.gnu} client certificates on the fly. - -Note that the proxy uses libcurl. Make sure your version of libcurl uses -GnuTLS and NOT OpenSSL. The proxy will @b{not} work with libcurl compiled -against OpenSSL. - -You can check the configuration your libcurl was build with by -running: - -@example -curl --version -@end example - -the output will look like this (without the linebreaks): - -@example -gnurl --version -curl 7.56.0 (x86_64-unknown-linux-gnu) libcurl/7.56.0 \ -GnuTLS/3.5.13 zlib/1.2.11 libidn2/2.0.4 -Release-Date: 2017-10-08 -Protocols: http https -Features: AsynchDNS IDN IPv6 Largefile NTLM SSL libz \ -TLS-SRP UnixSockets HTTPS-proxy -@end example - -@node Testing the GNS setup -@subsubsection Testing the GNS setup - -Now for testing purposes we can create some records in our zone to test -the SSL functionality of the proxy: - -@example -$ gnunet-identity -C test -$ gnunet-namestore -a -e "1 d" -n "homepage" \ - -t A -V 131.159.74.67 -z test -$ gnunet-namestore -a -e "1 d" -n "homepage" \ - -t LEHO -V "gnunet.org" -z test -@end example - -@noindent -At this point we can start the proxy. Simply execute - -@example -$ gnunet-gns-proxy -@end example - -@noindent -Configure your browser to use this SOCKSv5 proxy on port 7777 and visit -this link. -If you use @command{Firefox} (or one of its derivatives/forks such as -Icecat) you also have to go to @code{about:config} and set the key -@code{network.proxy.socks_remote_dns} to @code{true}. - -When you visit @code{https://homepage.test/}, you should get to the -@code{https://gnunet.org/} frontpage and the browser (with the correctly -configured proxy) should give you a valid SSL certificate for -@code{homepage.gnu} and no warnings. It should look like this: - -@c FIXME: Image does not exist, create it or save it from Drupal? -@c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser} - - -@node Configuring the GNUnet VPN -@subsection Configuring the GNUnet VPN - -@menu -* IPv4 address for interface:: -* IPv6 address for interface:: -* Configuring the GNUnet VPN DNS:: -* Configuring the GNUnet VPN Exit Service:: -* IP Address of external DNS resolver:: -* IPv4 address for Exit interface:: -* IPv6 address for Exit interface:: -@end menu - -Before configuring the GNUnet VPN, please make sure that system-wide DNS -interception is configured properly as described in the section on the -GNUnet DNS setup. @pxref{Configuring the GNU Name System}, -if you haven't done so already. - -The default options for the GNUnet VPN are usually sufficient to use -GNUnet as a Layer 2 for your Internet connection. -However, what you always have to specify is which IP protocol you want -to tunnel: IPv4, IPv6 or both. -Furthermore, if you tunnel both, you most likely should also tunnel -all of your DNS requests. -You theoretically can tunnel "only" your DNS traffic, but that usually -makes little sense. - -The other options as shown on the gnunet-setup tool are: - -@node IPv4 address for interface -@subsubsection IPv4 address for interface - -This is the IPv4 address the VPN interface will get. You should pick an -'private' IPv4 network that is not yet in use for you system. For example, -if you use @code{10.0.0.1/255.255.0.0} already, you might use -@code{10.1.0.1/255.255.0.0}. -If you use @code{10.0.0.1/255.0.0.0} already, then you might use -@code{192.168.0.1/255.255.0.0}. -If your system is not in a private IP-network, using any of the above will -work fine. -You should try to make the mask of the address big enough -(@code{255.255.0.0} or, even better, @code{255.0.0.0}) to allow more -mappings of remote IP Addresses into this range. -However, even a @code{255.255.255.0} mask will suffice for most users. - -@node IPv6 address for interface -@subsubsection IPv6 address for interface - -The IPv6 address the VPN interface will get. Here you can specify any -non-link-local address (the address should not begin with @code{fe80:}). -A subnet Unique Local Unicast (@code{fd00::/8} prefix) that you are -currently not using would be a good choice. - -@node Configuring the GNUnet VPN DNS -@subsubsection Configuring the GNUnet VPN DNS - -To resolve names for remote nodes, activate the DNS exit option. - -@node Configuring the GNUnet VPN Exit Service -@subsubsection Configuring the GNUnet VPN Exit Service - -If you want to allow other users to share your Internet connection (yes, -this may be dangerous, just as running a Tor exit node) or want to -provide access to services on your host (this should be less dangerous, -as long as those services are secure), you have to enable the GNUnet exit -daemon. - -You then get to specify which exit functions you want to provide. By -enabling the exit daemon, you will always automatically provide exit -functions for manually configured local services (this component of the -system is under -development and not documented further at this time). As for those -services you explicitly specify the target IP address and port, there is -no significant security risk in doing so. - -Furthermore, you can serve as a DNS, IPv4 or IPv6 exit to the Internet. -Being a DNS exit is usually pretty harmless. However, enabling IPv4 or -IPv6-exit without further precautions may enable adversaries to access -your local network, send spam, attack other systems from your Internet -connection and to other mischief that will appear to come from your -machine. This may or may not get you into legal trouble. -If you want to allow IPv4 or IPv6-exit functionality, you should strongly -consider adding additional firewall rules manually to protect your local -network and to restrict outgoing TCP traffic (i.e. by not allowing access -to port 25). While we plan to improve exit-filtering in the future, -you're currently on your own here. -Essentially, be prepared for any kind of IP-traffic to exit the respective -TUN interface (and GNUnet will enable IP-forwarding and NAT for the -interface automatically). - -Additional configuration options of the exit as shown by the gnunet-setup -tool are: - -@node IP Address of external DNS resolver -@subsubsection IP Address of external DNS resolver - -If DNS traffic is to exit your machine, it will be send to this DNS -resolver. You can specify an IPv4 or IPv6 address. - -@node IPv4 address for Exit interface -@subsubsection IPv4 address for Exit interface - -This is the IPv4 address the Interface will get. Make the mask of the -address big enough (255.255.0.0 or, even better, 255.0.0.0) to allow more -mappings of IP addresses into this range. As for the VPN interface, any -unused, private IPv4 address range will do. - -@node IPv6 address for Exit interface -@subsubsection IPv6 address for Exit interface - -The public IPv6 address the interface will get. If your kernel is not a -very recent kernel and you are willing to manually enable IPv6-NAT, the -IPv6 address you specify here must be a globally routed IPv6 address of -your host. - -Suppose your host has the address @code{2001:4ca0::1234/64}, then -using @code{2001:4ca0::1:0/112} would be fine (keep the first 64 bits, -then change at least one bit in the range before the bitmask, in the -example above we changed bit 111 from 0 to 1). - -You may also have to configure your router to route traffic for the entire -subnet (@code{2001:4ca0::1:0/112} for example) through your computer (this -should be automatic with IPv6, but obviously anything can be -disabled). - -@node Bandwidth Configuration -@subsection Bandwidth Configuration - -You can specify how many bandwidth GNUnet is allowed to use to receive -and send data. This is important for users with limited bandwidth or -traffic volume. - -@node Configuring NAT -@subsection Configuring NAT - -Most hosts today do not have a normal global IP address but instead are -behind a router performing Network Address Translation (NAT) which assigns -each host in the local network a private IP address. -As a result, these machines cannot trivially receive inbound connections -from the Internet. GNUnet supports NAT traversal to enable these machines -to receive incoming connections from other peers despite their -limitations. - -In an ideal world, you can press the "Attempt automatic configuration" -button in gnunet-setup to automatically configure your peer correctly. -Alternatively, your distribution might have already triggered this -automatic configuration during the installation process. -However, automatic configuration can fail to determine the optimal -settings, resulting in your peer either not receiving as many connections -as possible, or in the worst case it not connecting to the network at all. - -To manually configure the peer, you need to know a few things about your -network setup. First, determine if you are behind a NAT in the first -place. -This is always the case if your IP address starts with "10.*" or -"192.168.*". Next, if you have control over your NAT router, you may -choose to manually configure it to allow GNUnet traffic to your host. -If you have configured your NAT to forward traffic on ports 2086 (and -possibly 1080) to your host, you can check the "NAT ports have been opened -manually" option, which corresponds to the "PUNCHED_NAT" option in the -configuration file. If you did not punch your NAT box, it may still be -configured to support UPnP, which allows GNUnet to automatically -configure it. In that case, you need to install the "upnpc" command, -enable UPnP (or PMP) on your NAT box and set the "Enable NAT traversal -via UPnP or PMP" option (corresponding to "ENABLE_UPNP" in the -configuration file). - -Some NAT boxes can be traversed using the autonomous NAT traversal method. -This requires certain GNUnet components to be installed with "SUID" -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. - - -@node Peer configuration for distributions -@subsection Peer configuration for distributions - -The "GNUNET_DATA_HOME" in "[path]" in @file{/etc/gnunet.conf} should be -manually set to "/var/lib/gnunet/data/" as the default -"~/.local/share/gnunet/" is probably not that appropriate in this case. -Similarly, distributions may consider pointing "GNUNET_RUNTIME_DIR" to -"/var/run/gnunet/" and "GNUNET_HOME" to "/var/lib/gnunet/". Also, should a -distribution decide to override system defaults, all of these changes -should be done in a custom @file{/etc/gnunet.conf} and not in the files -in the @file{config.d/} directory. - -Given the proposed access permissions, the "gnunet-setup" tool must be -run as use "gnunet" (and with option "-c /etc/gnunet.conf" so that it -modifies the system configuration). As always, gnunet-setup should be run -after the GNUnet peer was stopped using "gnunet-arm -e". Distributions -might want to include a wrapper for gnunet-setup that allows the -desktop-user to "sudo" (i.e. using gtksudo) to the "gnunet" user account -and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in -sequence. - -@node MOVE TO INSTALL Checking the Installation -@section MOVE TO INSTALL Checking the Installation -@c %**end of header - -This section describes a quick, casual way to check if your GNUnet -installation works. However, if it does not, we do not cover -steps for recovery --- for this, please study the instructions -provided in the developer handbook as well as the system-specific -instruction in the source code repository@footnote{The system specific instructions are not provided as part of this handbook!}. - - -@menu -* gnunet-gtk:: -* Statistics:: -* Peer Information:: -@end menu - -@cindex GNUnet GTK -@cindex GTK -@cindex GTK user interface -@node gnunet-gtk -@subsection gnunet-gtk -@c %**end of header - -The @command{gnunet-gtk} package contains several graphical -user interfaces for the respective GNUnet applications. -Currently these interfaces cover: - -@itemize @bullet -@item Statistics -@item Peer Information -@item GNU Name System -@item File Sharing -@item Identity Management -@item Conversation -@end itemize - -@node Statistics -@subsection Statistics -@c %**end of header - -First, you should launch GNUnet gtk@footnote{Obviously you should also start gnunet, via gnunet-arm or the system provided method}. -You can do this from the command-line by typing - -@example -gnunet-statistics-gtk -@end example - -If your peer@footnote{The term ``peer'' is a common word used in federated and distributed networks to describe a participating device which is connected to the network. Thus, your Personal Computer or whatever it is you are looking at the Gtk+ interface describes a ``Peer'' or a ``Node''.} -is running correctly, you should see a bunch of lines, -all of which should be ``significantly'' above zero (at least if your -peer has been running for more than a few seconds). The lines indicate -how many other peers your peer is connected to (via different -mechanisms) and how large the entire overlay network is currently -estimated to be. The X-axis represents time (in seconds since the -start of @command{gnunet-gtk}). - -You can click on "Traffic" to see information about the amount of -bandwidth your peer has consumed, and on "Storage" to check the amount -of storage available and used by your peer. Note that "Traffic" is -plotted cumulatively, so you should see a strict upwards trend in the -traffic. - -@node Peer Information -@subsection Peer Information -@c %**end of header - -First, you should launch the graphical user interface. You can do -this from the command-line by typing - -@example -$ gnunet-peerinfo-gtk -@end example - -Once you have done this, you will see a list of known peers (by the -first four characters of their public key), their friend status (all -should be marked as not-friends initially), their connectivity (green -is connected, red is disconnected), assigned bandwidth, country of -origin (if determined) and address information. If hardly any peers -are listed and/or if there are very few peers with a green light for -connectivity, there is likely a problem with your network -configuration. - -@node MOVE TO INSTALL Config Leftovers -@section MOVE TO INSTALL Config Leftovers - -This section describes how to start a GNUnet peer. It assumes that you -have already compiled and installed GNUnet and its' dependencies. -Before you start a GNUnet peer, you may want to create a configuration -file using gnunet-setup (but you do not have to). -Sane defaults should exist in your -@file{$GNUNET_PREFIX/share/gnunet/config.d/} directory, so in practice -you could simply start without any configuration. If you want to -configure your peer later, you need to stop it before invoking the -@code{gnunet-setup} tool to customize further and to test your -configuration (@code{gnunet-setup} has build-in test functions). - -The most important option you might have to still set by hand is in -[PATHS]. Here, you use the option "GNUNET_HOME" to specify the path where -GNUnet should store its data. -It defaults to @code{$HOME/}, which again should work for most users. -Make sure that the directory specified as GNUNET_HOME is writable to -the user that you will use to run GNUnet (note that you can run frontends -using other users, GNUNET_HOME must only be accessible to the user used to -run the background processes). - -You will also need to make one central decision: should all of GNUnet be -run under your normal UID, or do you want distinguish between system-wide -(user-independent) GNUnet services and personal GNUnet services. The -multi-user setup is slightly more complicated, but also more secure and -generally recommended. - -@menu -* The Single-User Setup:: -* The Multi-User Setup:: -* Killing GNUnet services:: -* Access Control for GNUnet:: -@end menu - -@node The Single-User Setup -@subsection The Single-User Setup - -For the single-user setup, you do not need to do anything special and can -just start the GNUnet background processes using @code{gnunet-arm}. -By default, GNUnet looks in @file{~/.config/gnunet.conf} for a -configuration (or @code{$XDG_CONFIG_HOME/gnunet.conf} if@ -@code{$XDG_CONFIG_HOME} is defined). If your configuration lives -elsewhere, you need to pass the @code{-c FILENAME} option to all GNUnet -commands. - -Assuming the configuration file is called @file{~/.config/gnunet.conf}, -you start your peer using the @code{gnunet-arm} command (say as user -@code{gnunet}) using: - -@example -gnunet-arm -c ~/.config/gnunet.conf -s -@end example - -@noindent -The "-s" option here is for "start". The command should return almost -instantly. If you want to stop GNUnet, you can use: - -@example -gnunet-arm -c ~/.config/gnunet.conf -e -@end example - -@noindent -The "-e" option here is for "end". - -Note that this will only start the basic peer, no actual applications -will be available. -If you want to start the file-sharing service, use (after starting -GNUnet): - -@example -gnunet-arm -c ~/.config/gnunet.conf -i fs -@end example - -@noindent -The "-i fs" option here is for "initialize" the "fs" (file-sharing) -application. You can also selectively kill only file-sharing support using - -@example -gnunet-arm -c ~/.config/gnunet.conf -k fs -@end example - -@noindent -Assuming that you want certain services (like file-sharing) to be always -automatically started whenever you start GNUnet, you can activate them by -setting "IMMEDIATE_START=YES" in the respective section of the configuration -file (for example, "[fs]"). Then GNUnet with file-sharing support would -be started whenever you@ enter: - -@example -gnunet-arm -c ~/.config/gnunet.conf -s -@end example - -@noindent -Alternatively, you can combine the two options: - -@example -gnunet-arm -c ~/.config/gnunet.conf -s -i fs -@end example - -@noindent -Using @code{gnunet-arm} is also the preferred method for initializing -GNUnet from @code{init}. - -Finally, you should edit your @code{crontab} (using the @code{crontab} -command) and insert a line@ - -@example -@@reboot gnunet-arm -c ~/.config/gnunet.conf -s -@end example - -to automatically start your peer whenever your system boots. - -@node The Multi-User Setup -@subsection The Multi-User Setup - -This requires you to create a user @code{gnunet} and an additional group -@code{gnunetdns}, prior to running @code{make install} during -installation. -Then, you create a configuration file @file{/etc/gnunet.conf} which should -contain the lines:@ - -@example -[arm] -START_SYSTEM_SERVICES = YES -START_USER_SERVICES = NO -@end example - -@noindent -Then, perform the same steps to run GNUnet as in the per-user -configuration, except as user @code{gnunet} (including the -@code{crontab} installation). -You may also want to run @code{gnunet-setup} to configure your peer -(databases, etc.). -Make sure to pass @code{-c /etc/gnunet.conf} to all commands. If you -run @code{gnunet-setup} as user @code{gnunet}, you might need to change -permissions on @file{/etc/gnunet.conf} so that the @code{gnunet} user can -write to the file (during setup). - -Afterwards, you need to perform another setup step for each normal user -account from which you want to access GNUnet. First, grant the normal user -(@code{$USER}) permission to the group gnunet: - -@example -# adduser $USER gnunet -@end example - -@noindent -Then, create a configuration file in @file{~/.config/gnunet.conf} for the -$USER with the lines: - -@example -[arm] -START_SYSTEM_SERVICES = NO -START_USER_SERVICES = YES -@end example - -@noindent -This will ensure that @code{gnunet-arm} when started by the normal user -will only run services that are per-user, and otherwise rely on the -system-wide services. -Note that the normal user may run gnunet-setup, but the -configuration would be ineffective as the system-wide services will use -@file{/etc/gnunet.conf} and ignore options set by individual users. - -Again, each user should then start the peer using -@file{gnunet-arm -s} --- and strongly consider adding logic to start -the peer automatically to their crontab. - -Afterwards, you should see two (or more, if you have more than one USER) -@code{gnunet-service-arm} processes running in your system. - -@node Killing GNUnet services -@subsection Killing GNUnet services - -It is not necessary to stop GNUnet services explicitly when shutting -down your computer. - -It should be noted that manually killing "most" of the -@code{gnunet-service} processes is generally not a successful method for -stopping a peer (since @code{gnunet-service-arm} will instantly restart -them). The best way to explicitly stop a peer is using -@code{gnunet-arm -e}; note that the per-user services may need to be -terminated before the system-wide services will terminate normally. - -@node Access Control for GNUnet -@subsection Access Control for GNUnet - -This chapter documents how we plan to make access control work within the -GNUnet system for a typical peer. It should be read as a best-practice -installation guide for advanced users and builders of binary -distributions. The recommendations in this guide apply to POSIX-systems -with full support for UNIX domain sockets only. - -Note that this is an advanced topic. The discussion presumes a very good -understanding of users, groups and file permissions. Normal users on -hosts with just a single user can just install GNUnet under their own -account (and possibly allow the installer to use SUDO to grant additional -permissions for special GNUnet tools that need additional rights). -The discussion below largely applies to installations where multiple users -share a system and to installations where the best possible security is -paramount. - -A typical GNUnet system consists of components that fall into four -categories: - -@table @asis - -@item User interfaces -User interfaces are not security sensitive and are supposed to be run and -used by normal system users. -The GTK GUIs and most command-line programs fall into this category. -Some command-line tools (like gnunet-transport) should be excluded as they -offer low-level access that normal users should not need. -@item System services and support tools -System services should always run and offer services that can then be -accessed by the normal users. -System services do not require special permissions, but as they are not -specific to a particular user, they probably should not run as a -particular user. Also, there should typically only be one GNUnet peer per -host. System services include the gnunet-service and gnunet-daemon -programs; support tools include command-line programs such as gnunet-arm. -@item Privileged helpers -Some GNUnet components require root rights to open raw sockets or perform -other special operations. These gnunet-helper binaries are typically -installed SUID and run from services or daemons. -@item Critical services -Some GNUnet services (such as the DNS service) can manipulate the service -in deep and possibly highly security sensitive ways. For example, the DNS -service can be used to intercept and alter any DNS query originating from -the local machine. Access to the APIs of these critical services and their -privileged helpers must be tightly controlled. -@end table - -@c FIXME: The titles of these chapters are too long in the index. - -@menu -* Recommendation - Disable access to services via TCP:: -* Recommendation - Run most services as system user "gnunet":: -* Recommendation - Control access to services using group "gnunet":: -* Recommendation - Limit access to certain SUID binaries by group "gnunet":: -* Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns":: -* Differences between "make install" and these recommendations:: -@end menu - -@node Recommendation - Disable access to services via TCP -@subsubsection Recommendation - Disable access to services via TCP - -GNUnet services allow two types of access: via TCP socket or via UNIX -domain socket. -If the service is available via TCP, access control can only be -implemented by restricting connections to a particular range of IP -addresses. -This is acceptable for non-critical services that are supposed to be -available to all users on the local system or local network. -However, as TCP is generally less efficient and it is rarely the case -that a single GNUnet peer is supposed to serve an entire local network, -the default configuration should disable TCP access to all GNUnet -services on systems with support for UNIX domain sockets. -As of GNUnet 0.9.2, configuration files with TCP access disabled should be -generated by default. Users can re-enable TCP access to particular -services simply by specifying a non-zero port number in the section of -the respective service. - - -@node Recommendation - Run most services as system user "gnunet" -@subsubsection Recommendation - Run most services as system user "gnunet" - -GNUnet's main services should be run as a separate user "gnunet" in a -special group "gnunet". -The user "gnunet" should start the peer using "gnunet-arm -s" during -system startup. The home directory for this user should be -@file{/var/lib/gnunet} and the configuration file should be -@file{/etc/gnunet.conf}. -Only the @code{gnunet} user should have the right to access -@file{/var/lib/gnunet} (@emph{mode: 700}). - -@node Recommendation - Control access to services using group "gnunet" -@subsubsection Recommendation - Control access to services using group "gnunet" - -Users that should be allowed to use the GNUnet peer should be added to the -group "gnunet". Using GNUnet's access control mechanism for UNIX domain -sockets, those services that are considered useful to ordinary users -should be made available by setting "UNIX_MATCH_GID=YES" for those -services. -Again, as shipped, GNUnet provides reasonable defaults. -Permissions to access the transport and core subsystems might additionally -be granted without necessarily causing security concerns. -Some services, such as DNS, must NOT be made accessible to the "gnunet" -group (and should thus only be accessible to the "gnunet" user and -services running with this UID). - -@node Recommendation - Limit access to certain SUID binaries by group "gnunet" -@subsubsection Recommendation - Limit access to certain SUID binaries by group "gnunet" - -Most of GNUnet's SUID binaries should be safe even if executed by normal -users. However, it is possible to reduce the risk a little bit more by -making these binaries owned by the group "gnunet" and restricting their -execution to user of the group "gnunet" as well (4750). - -@node Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" -@subsubsection Recommendation - Limit access to critical gnunet-helper-dns to group "gnunetdns" - -A special group "gnunetdns" should be created for controlling access to -the "gnunet-helper-dns". -The binary should then be owned by root and be in group "gnunetdns" and -be installed SUID and only be group-executable (2750). -@b{Note that the group "gnunetdns" should have no users in it at all, -ever.} -The "gnunet-service-dns" program should be executed by user "gnunet" (via -gnunet-service-arm) with the binary owned by the user "root" and the group -"gnunetdns" and be SGID (2700). This way, @strong{only} -"gnunet-service-dns" can change its group to "gnunetdns" and execute the -helper, and the helper can then run as root (as per SUID). -Access to the API offered by "gnunet-service-dns" is in turn restricted -to the user "gnunet" (not the group!), which means that only -"benign" services can manipulate DNS queries using "gnunet-service-dns". - -@node Differences between "make install" and these recommendations -@subsubsection Differences between "make install" and these recommendations - -The current build system does not set all permissions automatically based -on the recommendations above. In particular, it does not use the group -"gnunet" at all (so setting gnunet-helpers other than the -gnunet-helper-dns to be owned by group "gnunet" must be done manually). -Furthermore, 'make install' will silently fail to set the DNS binaries to -be owned by group "gnunetdns" unless that group already exists (!). -An alternative name for the "gnunetdns" group can be specified using the -@code{--with-gnunetdns=GRPNAME} configure option. - diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi index 5ba6f6b15..2ef5a2b59 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi @@ -108,7 +108,7 @@ Philosophy * Design Principles:: * Privacy and Anonymity:: -* Practicality:: +* Practicality:: Key Concepts @@ -134,9 +134,6 @@ Using GNUnet * File-sharing:: * The GNU Name System:: * Using the Virtual Public Network:: -* MOVE TO INSTALL The graphical configuration interface:: -* MOVE TO INSTALL Checking the Installation:: -* MOVE TO INSTALL Config Leftovers:: GNUnet Contributors Handbook -- 2.25.1