From 42e5187e98fb01422b0d093d81c1b7235837257f Mon Sep 17 00:00:00 2001 From: ng0 Date: Wed, 25 Oct 2017 14:55:56 +0000 Subject: [PATCH] documentation batch commit --- doc/documentation/Makefile.am | 3 + doc/documentation/chapters/configuration.texi | 5 + doc/documentation/chapters/developer.texi | 447 +++++----- doc/documentation/chapters/installation.texi | 809 +++++++++--------- doc/documentation/chapters/philosophy.texi | 15 +- doc/documentation/gnunet.texi | 7 +- 6 files changed, 700 insertions(+), 586 deletions(-) create mode 100644 doc/documentation/chapters/configuration.texi diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am index c95728d25..c08d296bd 100644 --- a/doc/documentation/Makefile.am +++ b/doc/documentation/Makefile.am @@ -115,6 +115,7 @@ gnunet_TEXINFOS = \ chapters/philosophy.texi \ chapters/user.texi \ chapters/vocabulary.texi \ + chapters/configuration.texi \ fdl-1.3.texi \ gpl-3.0.texi @@ -134,6 +135,8 @@ DISTCLEANFILES = \ chapters/installation.cps \ chapter/philosophy.cps \ chapters/user.cps \ + chapters/configuration.cps \ + chapters/vocabulary.cps \ fdl-1.3.cps \ gpl-3.0.cps diff --git a/doc/documentation/chapters/configuration.texi b/doc/documentation/chapters/configuration.texi new file mode 100644 index 000000000..286c72e7a --- /dev/null +++ b/doc/documentation/chapters/configuration.texi @@ -0,0 +1,5 @@ +@node Configuration Handbook +@chapter Configuration Handbook + +This chapter has yet to be written. It is intended to be about in-depth +configuration of GNUnet. diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi index fcf4ede3a..d5b21a78c 100644 --- a/doc/documentation/chapters/developer.texi +++ b/doc/documentation/chapters/developer.texi @@ -9,13 +9,13 @@ application. For developers, GNUnet is: @itemize @bullet @item Free software under the GNU General Public License, with a community that believes in the GNU philosophy -@item -A set of standards, including coding conventions and architectural rules -@item -A set of layered protocols, both specifying the communication between -peers as well as the communication between components of a single peer. -@item -A set of libraries with well-defined APIs suitable for writing extensions +@item A set of standards, including coding conventions and +architectural rules +@item A set of layered protocols, both specifying the communication +between peers as well as the communication between components +of a single peer +@item A set of libraries with well-defined APIs suitable for +writing extensions @end itemize In particular, the architecture specifies that a peer consists of many @@ -25,34 +25,12 @@ for writing extensions. It is possible to write extensions in other languages by implementing the necessary IPC protocols. GNUnet can be extended and improved along many possible dimensions, and -anyone interested in free software and freedom-enhancing networking is -welcome to join the effort. This developer handbook attempts to provide +anyone interested in Free Software and Freedom-enhancing Networking is +welcome to join the effort. This Developer Handbook attempts to provide an initial introduction to some of the key design choices and central -components of the system. This manual is far from complete, and we -welcome informed contributions, be it in the form of new chapters or -insightful comments. - -However, the website is experiencing a constant onslaught of sophisticated -link-spam entered manually by exploited workers solving puzzles and -customizing text. To limit this commercial defacement, we are strictly -moderating comments and have disallowed "normal" users from posting new -content. However, this is really only intended to keep the spam at bay. If -you are a real user or aspiring developer, please drop us a note -(IRC, e-mail, contact form) with your user profile ID number included. -We will then relax these restrictions on your account. We're sorry for -this inconvenience; however, few people would want to read this site -if 99% of it was advertisements for bogus websites. - - - -@c *********************************************************************** - - - - - - - +components of the system. This part of the GNUNet documentation +is far from complete, and we welcome informed contributions, +be it in the form of new chapters or insightful comments. @menu * Developer Introduction:: @@ -96,7 +74,7 @@ if 99% of it was advertisements for bogus websites. @node Developer Introduction @section Developer Introduction -This developer handbook is intended as first introduction to GNUnet for +This Developer Handbook is intended as first introduction to GNUnet for new developers that want to extend the GNUnet framework. After the introduction, each of the GNUnet subsystems (directories in the @file{src/} tree) is (supposed to be) covered in its own chapter. In @@ -125,34 +103,44 @@ GNUnet's maintainer. The public subsystems on the GNUnet server that help developers are: @itemize @bullet -@item The Version control system keeps our code and enables distributed -development. Only developers with write access can commit code, everyone -else is encouraged to submit patches to the + +@item The Version control system (git) keeps our code and enables +distributed development. +Only developers with write access can commit code, everyone else is +encouraged to submit patches to the @uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, GNUnet-developers mailinglist} . -@item The GNUnet bugtracking system is used to track feature requests, -open bug reports and their resolutions. Anyone can report bugs, only -developers can claim to have fixed them. -@item A buildbot is used to check GNUnet builds automatically on a range -of platforms. Builds are triggered automatically after 30 minutes of no -changes to Git. + +@item The GNUnet bugtracking system (Mantis) is used to track +feature requests, open bug reports and their resolutions. +Anyone can report bugs, only developers can claim to have fixed them. + +@item A site installation of the CI system "Buildbot" is used to check +GNUnet builds automatically on a range of platforms. +Builds are triggered automatically after 30 minutes of no changes to Git. + @item The current quality of our automated test suite is assessed using Code coverage analysis. This analysis is run daily; however the webpage is only updated if all automated tests pass at that time. Testcases that improve our code coverage are always welcome. + @item We try to automatically find bugs using a static analysis scan. This scan is run daily; however the webpage is only updated if all automated tests pass at the time. Note that not everything that is flagged by the analysis is a bug, sometimes even good code can be marked as possibly problematic. Nevertheless, developers are encouraged to at least be aware of all issues in their code that are listed. + @item We use Gauger for automatic performance regression visualization. Details on how to use Gauger are here. + @item We use @uref{http://junit.org/, junit} to automatically test -gnunet-java. Automatically generated, current reports on the test suite -are here. +@command{gnunet-java}. +Automatically generated, current reports on the test suite are here. + @item We use Cobertura to generate test coverage reports for gnunet-java. Current reports on test coverage are here. + @end itemize @@ -175,26 +163,34 @@ GNUnet sub-projects in order of likely relevance are currently: @table @asis -@item gnunet Core of the P2P framework, including file-sharing, VPN and +@item gnunet +Core of the P2P framework, including file-sharing, VPN and chat applications; this is what the developer handbook covers mostly @item gnunet-gtk Gtk+-based user interfaces, including gnunet-fs-gtk (file-sharing), gnunet-statistics-gtk (statistics over time), gnunet-peerinfo-gtk (information about current connections and known peers), gnunet-chat-gtk (chat GUI) and gnunet-setup (setup tool for "everything") -@item gnunet-fuse Mounting directories shared via GNUnet's file-sharing +@item gnunet-fuse +Mounting directories shared via GNUnet's file-sharing on Linux -@item gnunet-update Installation and update tool -@item gnunet-ext Template for starting 'external' GNUnet projects -@item gnunet-java Java APIs for writing GNUnet services and applications +@item gnunet-update +Installation and update tool +@item gnunet-ext +Template for starting 'external' GNUnet projects +@item gnunet-java +Java APIs for writing GNUnet services and applications @c ** FIXME: Point to new website repository once we have it: @c ** @item svn/gnunet-www/ Code and media helping drive the GNUnet -website -@item eclectic Code to run -GNUnet nodes on testbeds for research, development, testing and evaluation +@c website +@item eclectic +Code to run GNUnet nodes on testbeds for research, development, +testing and evaluation @c ** FIXME: Solve the status and location of gnunet-qt -@item gnunet-qt qt-based GNUnet GUI (dead?) -@item gnunet-cocoa cocoa-based GNUnet GUI (dead?) +@item gnunet-qt +Qt-based GNUnet GUI (dead?) +@item gnunet-cocoa +cocoa-based GNUnet GUI (dead?) @end table @@ -202,12 +198,19 @@ We are also working on various supporting libraries and tools: @c ** FIXME: What about gauger, and what about libmwmodem? @table @asis -@item libextractor GNU libextractor (meta data extraction) -@item libmicrohttpd GNU libmicrohttpd (embedded HTTP(S) server library) -@item gauger Tool for performance regression analysis -@item monkey Tool for automated debugging of distributed systems -@item libmwmodem Library for accessing satellite connection quality +@item libextractor +GNU libextractor (meta data extraction) +@item libmicrohttpd +GNU libmicrohttpd (embedded HTTP(S) server library) +@item gauger +Tool for performance regression analysis +@item monkey +Tool for automated debugging of distributed systems +@item libmwmodem +Library for accessing satellite connection quality reports +@item libgnurl +gnURL (feature restricted variant of cURL/libcurl) @end table Finally, there are various external projects (see links for a list of @@ -224,100 +227,116 @@ the @file{gnunet/src/} directory. The order given is roughly bottom-up (in terms of the layers of the system). @table @asis -@item util/ --- libgnunetutil Library with general utility functions, all +@item @file{util/} --- libgnunetutil +Library with general utility functions, all GNUnet binaries link against this library. Anything from memory allocation and data structures to cryptography and inter-process communication. The goal is to provide an OS-independent interface and more 'secure' or convenient implementations of commonly used primitives. The API is spread over more than a dozen headers, developers should study those closely to avoid duplicating existing functions. -@item hello/ --- libgnunethello HELLO messages are used to +@item @file{hello/} --- libgnunethello +HELLO messages are used to describe under which addresses a peer can be reached (for example, protocol, IP, port). This library manages parsing and generating of HELLO messages. -@item block/ --- libgnunetblock The DHT and other components of GNUnet +@item @file{block/} --- libgnunetblock +The DHT and other components of GNUnet store information in units called 'blocks'. Each block has a type and the type defines a particular format and how that binary format is to be linked to a hash code (the key for the DHT and for databases). The block library is a wapper around block plugins which provide the necessary functions for each block type. -@item statistics/ The statistics service enables associating +@item @file{statistics/} +The statistics service enables associating values (of type uint64_t) with a componenet name and a string. The main uses is debugging (counting events), performance tracking and user entertainment (what did my peer do today?). -@item arm/ The automatic-restart-manager (ARM) service +@item @file{arm/} --- Automatic Restart Manager (ARM) +The automatic-restart-manager (ARM) service is the GNUnet master service. Its role is to start gnunet-services, to re-start them when they crashed and finally to shut down the system when requested. -@item peerinfo/ The peerinfo service keeps track of which peers are known +@item @file{peerinfo/} +The peerinfo service keeps track of which peers are known to the local peer and also tracks the validated addresses for each peer (in the form of a HELLO message) for each of those peers. The peer is not necessarily connected to all peers known to the peerinfo service. Peerinfo provides persistent storage for peer identities --- peers are not forgotten just because of a system restart. -@item datacache/ --- libgnunetdatacache The datacache -library provides (temporary) block storage for the DHT. Existing plugins -can store blocks in Sqlite, Postgres or MySQL databases. All data stored -in the cache is lost when the peer is stopped or restarted (datacache -uses temporary tables). -@item datastore/ The datastore service stores file-sharing blocks in +@item @file{datacache/} --- libgnunetdatacache +The datacache library provides (temporary) block storage for the DHT. +Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. +All data stored in the cache is lost when the peer is stopped or +restarted (datacache uses temporary tables). +@item @file{datastore/} +The datastore service stores file-sharing blocks in databases for extended periods of time. In contrast to the datacache, data is not lost when peers restart. However, quota restrictions may still cause old, expired or low-priority data to be eventually discarded. Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. -@item template/ Template for writing a new service. Does nothing. -@item ats/ The automatic transport +@item @file{template/} +Template for writing a new service. Does nothing. +@item @file{ats/} --- Automatic Transport Selection +The automatic transport selection (ATS) service is responsible for deciding which address (i.e. which transport plugin) should be used for communication with other peers, and at what bandwidth. -@item nat/ --- libgnunetnat Library that provides basic -functions for NAT traversal. The library supports NAT traversal with +@item @file{nat/} --- libgnunetnat +Library that provides basic functions for NAT traversal. +The library supports NAT traversal with manual hole-punching by the user, UPnP and ICMP-based autonomous NAT traversal. The library also includes an API for testing if the current configuration works and the @code{gnunet-nat-server} which provides an external service to test the local configuration. -@item fragmentation/ --- libgnunetfragmentation Some -transports (UDP and WLAN, mostly) have restrictions on the maximum +@item @file{fragmentation/} --- libgnunetfragmentation +Some transports (UDP and WLAN, mostly) have restrictions on the maximum transfer unit (MTU) for packets. The fragmentation library can be used to break larger packets into chunks of at most 1k and transmit the resulting fragments reliabily (with acknowledgement, retransmission, timeouts, etc.). -@item transport/ The transport service is responsible for managing the +@item @file{transport/} +The transport service is responsible for managing the basic P2P communication. It uses plugins to support P2P communication over TCP, UDP, HTTP, HTTPS and other protocols.The transport service validates peer addresses, enforces bandwidth restrictions, limits the total number of connections and enforces connectivity restrictions (i.e. friends-only). -@item peerinfo-tool/ +@item @file{peerinfo-tool/} This directory contains the gnunet-peerinfo binary which can be used to inspect the peers and HELLOs known to the peerinfo service. -@item core/ The core -service is responsible for establishing encrypted, authenticated +@item @file{core/} +The core service is responsible for establishing encrypted, authenticated connections with other peers, encrypting and decrypting messages and forwarding messages to higher-level services that are interested in them. -@item testing/ --- -libgnunettesting The testing library allows starting (and stopping) peers -for writing testcases.@ +@item @file{testing/} --- libgnunettesting +The testing library allows starting (and stopping) peers +for writing testcases. It also supports automatic generation of configurations for peers ensuring that the ports and paths are disjoint. libgnunettesting is also the foundation for the testbed service -@item testbed/ The testbed service is -used for creating small or large scale deployments of GNUnet peers for -evaluation of protocols. It facilitates peer depolyments on multiple +@item @file{testbed/} +The testbed service is used for creating small or large scale deployments +of GNUnet peers for evaluation of protocols. +It facilitates peer depolyments on multiple hosts (for example, in a cluster) and establishing varous network topologies (both underlay and overlay). -@item nse/ The network size estimation (NSE) service +@item @file{nse/} --- Network Size Estimation +The network size estimation (NSE) service implements a protocol for (securely) estimating the current size of the P2P network. -@item dht/ The distributed hash table (DHT) service provides a +@item @file{dht/} --- distributed hash table +The distributed hash table (DHT) service provides a distributed implementation of a hash table to store blocks under hash keys in the P2P network. -@item hostlist/ The hostlist service allows learning about +@item @file{hostlist/} +The hostlist service allows learning about other peers in the network by downloading HELLO messages from an HTTP server, can be configured to run such an HTTP server and also implements a P2P protocol to advertise and automatically learn about other peers that offer a public hostlist server. -@item topology/ The topology service is responsible for +@item @file{topology/} +The topology service is responsible for maintaining the mesh topology. It tries to maintain connections to friends (depending on the configuration) and also tries to ensure that the peer has a decent number of active connections at all times. If necessary, new @@ -326,90 +345,100 @@ otherwise they may end up not being connected to any other peer (unless some other service ensures that core establishes the required connections). The topology service also tells the transport service which connections are permitted (for friend-to-friend networking) -@item fs/ The file-sharing (FS) service implements GNUnet's +@item @file{fs/} --- file-sharing +The file-sharing (FS) service implements GNUnet's file-sharing application. Both anonymous file-sharing (using gap) and non-anonymous file-sharing (using dht) are supported. -@item cadet/ The CADET -service provides a general-purpose routing abstraction to create +@item @file{cadet/} +The CADET service provides a general-purpose routing abstraction to create end-to-end encrypted tunnels in mesh networks. We wrote a paper documenting key aspects of the design. -@item tun/ --- libgnunettun Library for building IPv4, IPv6 -packets and creating checksums for UDP, TCP and ICMP packets. The header +@item @file{tun/} --- libgnunettun +Library for building IPv4, IPv6 packets and creating +checksums for UDP, TCP and ICMP packets. The header defines C structs for common Internet packet formats and in particular structs for interacting with TUN (virtual network) interfaces. -@item mysql/ --- -libgnunetmysql Library for creating and executing prepared MySQL +@item @file{mysql/} --- libgnunetmysql +Library for creating and executing prepared MySQL statements and to manage the connection to the MySQL database. Essentially a lightweight wrapper for the interaction between GNUnet components and libmysqlclient. -@item dns/ Service that allows intercepting and modifying DNS requests of +@item @file{dns/} +Service that allows intercepting and modifying DNS requests of the local machine. Currently used for IPv4-IPv6 protocol translation (DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The service can also be configured to offer an exit service for DNS traffic. -@item vpn/ The virtual -public network (VPN) service provides a virtual tunnel interface (VTUN) -for IP routing over GNUnet. Needs some other peers to run an "exit" -service to work. +@item @file{vpn/} +The virtual public network (VPN) service provides a virtual +tunnel interface (VTUN) for IP routing over GNUnet. +Needs some other peers to run an "exit" service to work. Can be activated using the "gnunet-vpn" tool or integrated with DNS using the "pt" daemon. -@item exit/ Daemon to allow traffic from the VPN to exit this +@item @file{exit/} +Daemon to allow traffic from the VPN to exit this peer to the Internet or to specific IP-based services of the local peer. Currently, an exit service can only be restricted to IPv4 or IPv6, not to specific ports and or IP address ranges. If this is not acceptable, additional firewall rules must be added manually. exit currently only works for normal UDP, TCP and ICMP traffic; DNS queries need to leave the system via a DNS service. -@item pt/ protocol translation daemon. This daemon enables 4-to-6, +@item @file{pt/} +protocol translation daemon. This daemon enables 4-to-6, 6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It essentially uses "DNS" to intercept DNS replies and then maps results to those offered by the VPN, which then sends them using mesh to some daemon offering an appropriate exit service. -@item identity/ Management of egos (alter egos) of a user; identities are +@item @file{identity/} +Management of egos (alter egos) of a user; identities are essentially named ECC private keys and used for zones in the GNU name system and for namespaces in file-sharing, but might find other uses later -@item revocation/ Key revocation service, can be used to revoke the +@item @file{revocation/} +Key revocation service, can be used to revoke the private key of an identity if it has been compromised -@item namecache/ Cache -for resolution results for the GNU name system; data is encrypted and can -be shared among users, loss of the data should ideally only result in a +@item @file{namecache/} +Cache for resolution results for the GNU name system; +data is encrypted and can be shared among users, +loss of the data should ideally only result in a performance degradation (persistence not required) -@item namestore/ Database -for the GNU name system with per-user private information, persistence -required -@item gns/ GNU name system, a GNU approach to DNS and PKI. -@item dv/ A plugin -for distance-vector (DV)-based routing. DV consists of a service and a -transport plugin to provide peers with the illusion of a direct P2P -connection for connections that use multiple (typically up to 3) hops in -the actual underlay network. -@item regex/ Service for the (distributed) evaluation of -regular expressions. -@item scalarproduct/ The scalar product service offers an -API to perform a secure multiparty computation which calculates a scalar -product between two peers without exposing the private input vectors of -the peers to each other. -@item consensus/ The consensus service will allow a set -of peers to agree on a set of values via a distributed set union -computation. -@item rest/ The rest API allows access to GNUnet services using RESTful -interaction. The services provide plugins that can exposed by the rest -server. -@item experimentation/ The experimentation daemon coordinates distributed -experimentation to evaluate transport and ats properties +@item @file{namestore/} +Database for the GNU name system with per-user private information, +persistence required +@item @file{gns/} +GNU name system, a GNU approach to DNS and PKI. +@item @file{dv/} +A plugin for distance-vector (DV)-based routing. +DV consists of a service and a transport plugin to provide peers +with the illusion of a direct P2P connection for connections +that use multiple (typically up to 3) hops in the actual underlay network. +@item @file{regex/} +Service for the (distributed) evaluation of regular expressions. +@item @file{scalarproduct/} +The scalar product service offers an API to perform a secure multiparty +computation which calculates a scalar product between two peers +without exposing the private input vectors of the peers to each other. +@item @file{consensus/} +The consensus service will allow a set of peers to agree +on a set of values via a distributed set union computation. +@item @file{rest/} +The rest API allows access to GNUnet services using RESTful interaction. +The services provide plugins that can exposed by the rest server. +@item @file{experimentation/} +The experimentation daemon coordinates distributed +experimentation to evaluate transport and ATS properties. @end table @c *********************************************************************** @node System Architecture @section System Architecture -GNUnet developers like legos. The blocks are indestructible, can be +GNUnet developers like LEGOs. The blocks are indestructible, can be stacked together to construct complex buildings and it is generally easy to swap one block for a different one that has the same shape. GNUnet's -architecture is based on legos: +architecture is based on LEGOs: @c images here -This chapter documents the GNUnet lego system, also known as GNUnet's +This chapter documents the GNUnet LEGO system, also known as GNUnet's system architecture. The most common GNUnet component is a service. Services offer an API (or @@ -454,7 +483,7 @@ ARM. @node Subsystem stability @section Subsystem stability -This page documents the current stability of the various GNUnet +This section documents the current stability of the various GNUnet subsystems. Stability here describes the expected degree of compatibility with future versions of GNUnet. For each subsystem we distinguish between compatibility on the P2P network level (communication protocol between @@ -550,8 +579,6 @@ This subsystem does not have an API/IPC-protocol/P2P-protocol Here you can find some rules to help you write code for GNUnet. - - @c *********************************************************************** @menu * Naming conventions:: @@ -612,20 +639,31 @@ Here you can find some rules to help you write code for GNUnet. @subsubsection logging @itemize @bullet -@item services and daemons use their directory name in GNUNET_log_setup -(i.e. 'core') and log using plain 'GNUNET_log'. -@item command-line tools use their full name in GNUNET_log_setup (i.e. -'gnunet-publish') and log using plain 'GNUNET_log'. -@item service access libraries log using 'GNUNET_log_from' and use -'DIRNAME-api' for the component (i.e. 'core-api') -@item pure libraries (without associated service) use 'GNUNET_log_from' -with the component set to their library name (without lib or '.so'), -which should also be their directory name (i.e. 'nat') -@item plugins should use 'GNUNET_log_from' with the directory name and the -plugin name combined to produce the component name (i.e. 'transport-tcp'). -@item logging should be unified per-file by defining a LOG macro with the -appropriate arguments, along these lines:@ #define LOG(kind,...) +@item services and daemons use their directory name in +@code{GNUNET_log_setup} (i.e. 'core') and log using +plain 'GNUNET_log'. +@item command-line tools use their full name in +@code{GNUNET_log_setup} (i.e. 'gnunet-publish') and log using +plain 'GNUNET_log'. +@item service access libraries log using +'@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the +component (i.e. 'core-api') +@item pure libraries (without associated service) use +'@code{GNUNET_log_from}' with the component set to their +library name (without lib or '@file{.so}'), +which should also be their directory name (i.e. '@file{nat}') +@item plugins should use '@code{GNUNET_log_from}' +with the directory name and the plugin name combined to produce +the component name (i.e. 'transport-tcp'). +@item logging should be unified per-file by defining a +@code{LOG} macro with the appropriate arguments, +along these lines: + +@example +#define LOG(kind,...) GNUNET_log_from (kind, "example-api",__VA_ARGS__) +@end example + @end itemize @c *********************************************************************** @@ -633,10 +671,12 @@ GNUNET_log_from (kind, "example-api",__VA_ARGS__) @subsubsection configuration @itemize @bullet -@item paths (that are substituted in all filenames) are in PATHS (have as -few as possible) -@item all options for a particular module (src/MODULE) are under [MODULE] -@item options for a plugin of a module are under [MODULE-PLUGINNAME] +@item paths (that are substituted in all filenames) are in PATHS +(have as few as possible) +@item all options for a particular module (@file{src/MODULE}) +are under @code{[MODULE]} +@item options for a plugin of a module +are under @code{[MODULE-PLUGINNAME]} @end itemize @c *********************************************************************** @@ -644,9 +684,9 @@ few as possible) @subsubsection exported symbols @itemize @bullet -@item must start with "GNUNET_modulename_" and be defined in -"modulename.c" -@item exceptions: those defined in gnunet_common.h +@item must start with "@code{GNUNET_modulename_}" and be defined in +"@file{modulename.c}" +@item exceptions: those defined in @file{gnunet_common.h} @end itemize @c *********************************************************************** @@ -656,17 +696,17 @@ few as possible) @itemize @bullet @item must NOT start with any prefix @item must not be exported in a way that linkers could use them or@ other -libraries might see them via headers; they must be either@ -declared/defined in C source files or in headers that are in@ the -respective directory under src/modulename/ and NEVER be@ declared -in src/include/. +libraries might see them via headers; they must be either +declared/defined in C source files or in headers that are in the +respective directory under @file{src/modulename/} and NEVER be declared +in @file{src/include/}. @end itemize @node testcases @subsubsection testcases @itemize @bullet -@item must be called "test_module-under-test_case-description.c" +@item must be called "@file{test_module-under-test_case-description.c}" @item "case-description" maybe omitted if there is only one test @end itemize @@ -675,10 +715,10 @@ in src/include/. @subsubsection performance tests @itemize @bullet -@item must be called "perf_module-under-test_case-description.c" +@item must be called "@file{perf_module-under-test_case-description.c}" @item "case-description" maybe omitted if there is only one performance test -@item Must only be run if HAVE_BENCHMARKS is satisfied +@item Must only be run if @code{HAVE_BENCHMARKS} is satisfied @end itemize @c *********************************************************************** @@ -966,8 +1006,8 @@ export LD_LIBRARY_PATH=/path/to/gnunet/lib Ideally, any non-trivial GNUnet code should be covered by automated testcases. Testcases should reside in the same place as the code that is being tested. The name of source files implementing tests should begin -with "test_" followed by the name of the file that contains the code that -is being tested. +with "@code{test_}" followed by the name of the file +that contains the code that is being tested. Testcases in GNUnet should be integrated with the autotools build system. This way, developers and anyone building binary packages will be able to @@ -975,8 +1015,8 @@ run all testcases simply by running @code{make check}. The final testcases shipped with the distribution should output at most some brief progress information and not display debug messages by default. The success or failure of a testcase must be indicated by returning zero -(success) or non-zero (failure) from the main method of the testcase. The -integration with the autotools is relatively straightforward and only +(success) or non-zero (failure) from the main method of the testcase. +The integration with the autotools is relatively straightforward and only requires modifications to the @file{Makefile.am} in the directory containing the testcase. For a testcase testing the code in @file{foo.c} the @file{Makefile.am} would contain the following lines: @@ -992,8 +1032,9 @@ Naturally, other libraries used by the testcase may be specified in the @code{LDADD} directive as necessary. Often testcases depend on additional input files, such as a configuration -file. These support files have to be listed using the EXTRA_DIST +file. These support files have to be listed using the @code{EXTRA_DIST} directive in order to ensure that they are included in the distribution. + Example: @example @@ -1068,8 +1109,9 @@ maximum number of peers that are allowed to share a single instance of the shared service. TESTING system created with @code{GNUNET_TESTING_system_create()} chooses -ports from the default range 12000 - 56000 while auto-generating -configurations for peers. This range can be customised with the function +ports from the default range @code{12000} - @code{56000} while +auto-generating configurations for peers. +This range can be customised with the function @code{GNUNET_TESTING_system_create_with_portrange()}. This function is similar to @code{GNUNET_TESTING_system_create()} except that it take 2 additional parameters --- the start and end of the port range to use. @@ -1220,9 +1262,9 @@ random dependant metrics probably are not ideal candidates for meaningful regression detection. To start logging any value, just include @code{gauger.h} in your testcase -code. Then, use the macro @code{GAUGER()} to make the buildbots log +code. Then, use the macro @code{GAUGER()} to make the Buildbots log whatever value is of interest for you to @code{gnunet.org}'s Gauger -server. No setup is necessary as most buildbots have already everything +server. No setup is necessary as most Buildbots have already everything in place and new metrics are created on demand. To delete a metric, you need to contact a member of the GNUnet development team (a file will need to be removed manually from the respective directory). @@ -1242,7 +1284,6 @@ int main (int argc, char *argv[]) @{ "UNIT"); @} @end example - Where: @table @asis @@ -1370,8 +1411,9 @@ gnunet-helper-testbed On some systems, problems may arise while starting testbed helpers if GNUnet is installed into a custom location since the helper may not be found in the standard path. This can be addressed by setting the variable -`HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will -then use this path to start helper binaries both locally and remotely. +`@code{HELPER_BINARY_PATH}' to the path of the testbed helper. +Testbed API will then use this path to start helper binaries both +locally and remotely. Testbed API can accessed by including the "@file{gnunet_testbed_service.h}" file and linking with -lgnunettestbed. @@ -1479,14 +1521,16 @@ topologies. @xref{Topology file format}, for the format of this file. @node Hosts file format @subsection Hosts file format -The testbed API offers the function GNUNET_TESTBED_hosts_load_from_file() -to load from a given file details about the hosts which testbed can use -for deploying peers. This function is useful to keep the data about hosts +The testbed API offers the function +@code{GNUNET_TESTBED_hosts_load_from_file()} to load from a given file +details about the hosts which testbed can use for deploying peers. +This function is useful to keep the data about hosts separate instead of hard coding them in code. -Another helper function from testbed API, GNUNET_TESTBED_run() also takes -a hosts file name as its parameter. It uses the above function to -populate the hosts data structures and start controllers to deploy peers. +Another helper function from testbed API, @code{GNUNET_TESTBED_run()} +also takes a hosts file name as its parameter. It uses the above +function to populate the hosts data structures and start controllers to +deploy peers. These functions require the hosts file to be of the following format: @itemize @bullet @@ -1648,7 +1692,7 @@ downward propagation is for triggering that the barrier is crossed. @node Automatic large-scale deployment in the PlanetLab testbed @subsection Automatic large-scale deployment in the PlanetLab testbed -PlanetLab is as a testbed for computer networking and distributed systems +PlanetLab is a testbed for computer networking and distributed systems research. It was established in 2002 and as of June 2010 was composed of 1090 nodes at 507 sites worldwide. @@ -1678,7 +1722,7 @@ instructions how to install GNUnet on a PlanetLab node. @c ** Actually this is a subsubsubsection, but must be fixed differently @c ** as subsubsection is the lowest. -Since most of the PlanetLab nodes are running the very old fedora core 8 +Since most of the PlanetLab nodes are running the very old Fedora core 8 image, installing the buildslave software is quite some pain. For our PlanetLab testbed we figured out how to install the buildslave software best. @@ -1687,7 +1731,7 @@ best. @c FIXME: Is there an official, safer way instead of blind-piping a @c script? @c FIXME: Use newer pypi URLs below. -Install Distribute for python: +Install Distribute for Python: @example curl http://python-distribute.org/distribute_setup.py | sudo python @@ -3335,9 +3379,10 @@ crashed. ARM schedules it for restarting but after its new backoff time (which became 2ms), and doubles its backoff time (now backoff(S) = 4). @item and so on, until backoff(S) reaches a certain threshold -(EXPONENTIAL_BACKOFF_THRESHOLD is set to half an hour), after reaching it, -backoff(S) will remain half an hour, hence ARM won't be busy for a lot of -time trying to restart a problematic service. +(@code{EXPONENTIAL_BACKOFF_THRESHOLD} is set to half an hour), +after reaching it, backoff(S) will remain half an hour, +hence ARM won't be busy for a lot of time trying to restart a +problematic service. @end itemize @cindex TRANSPORT Subsystem @@ -3391,7 +3436,6 @@ applicable); outbound traffic limits are enforced by CORE, not by us (!) configuration and blacklisting clients @end itemize - Note that the term "clients" in the list above really refers to the GNUnet-CORE service, as CORE is typically the only client of the transport service. @@ -3423,7 +3467,7 @@ claims to be for Bob, but contains Mallory's IP address instead of Bobs (for some transport). Mallory would then forward the traffic to Bob (by initiating a connection to Bob and claiming to be Alice). As a further complication, the scheme has to work even if say Alice is behind a NAT -without traversal support and hence has no address of her own (and thus +without traversal support and hence has no address of their own (and thus Alice must always initiate the connection to Bob). An additional constraint is that HELLO messages do not contain a @@ -3438,21 +3482,24 @@ The solution is the following. If Alice wants to validate that a given address for Bob is valid (i.e. is actually established @strong{directly} with the intended target), it sends a PING message over that connection to Bob. Note that in this case, Alice initiated the connection so only -she knows which address was used for sure (Alice maybe behind NAT, so -whatever address Bob sees may not be an address Alice knows she has). Bob -checks that the address given in the PING is actually one of his addresses +Alice knows which address was used for sure (Alice maybe behind NAT, so +whatever address Bob sees may not be an address Alice knows they have). +Bob +checks that the address given in the PING is actually one of Bob's +addresses (does not belong to Mallory), and if it is, sends back a PONG (with a signature that says that Bob owns/uses the address from the PING). Alice checks the signature and is happy if it is valid and the address in the -PONG is the address she used. This is similar to the 0.8.x protocol where -the HELLO contained a signature from Bob for each address used by Bob. +PONG is the address Alice used. +This is similar to the 0.8.x protocol where the HELLO contained a +signature from Bob for each address used by Bob. Here, the purpose code for the signature is @code{GNUNET_SIGNATURE_PURPOSE_TRANSPORT_PONG_OWN}. After this, Alice will remember Bob's address and consider the address valid for a while (12h in the current implementation). Note that after this exchange, Alice only considers Bob's address to be valid, the connection itself is not considered 'established'. In particular, Alice may have many addresses -for Bob that she considers valid. +for Bob that Alice considers valid. The PONG message is protected with a nonce/challenge against replay attacks and uses an expiration time for the signature (but those are diff --git a/doc/documentation/chapters/installation.texi b/doc/documentation/chapters/installation.texi index 14175a6f7..cd3b4ae11 100644 --- a/doc/documentation/chapters/installation.texi +++ b/doc/documentation/chapters/installation.texi @@ -19,7 +19,7 @@ be it in the form of new chapters or insightful comments. * Installing GNUnet from Git on Ubuntu 14.4:: * Build instructions for Debian 8:: * Outdated build instructions for previous revisions:: -* Portable GNUnet:: +@c * Portable GNUnet:: * The graphical configuration interface:: * How to start and stop a GNUnet peer:: @end menu @@ -315,7 +315,8 @@ $ ./configure --with-gnunet=/usr/local/ $ make $ sudo make install $ cd .. -$ sudo ldconfig # just to be safe +# just to be safe run this: +$ sudo ldconfig @end example @noindent @@ -413,18 +414,20 @@ hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 @noindent The exact details may differ a bit, which is fine. Add the text -@emph{"gns [NOTFOUND=return]"} after @emph{"files"}: +@emph{"gns [NOTFOUND=return]"} after @emph{"files"}. +Keep in mind that we included a backslash ("\") here just for +markup reasons. You should write the text below on @b{one line} +and @b{without} the "\": @example -hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4 +hosts: files gns [NOTFOUND=return] mdns4_minimal \ +[NOTFOUND=return] dns mdns4 @end example - +@c FIXME: Document new behavior. You might want to make sure that @file{/lib/libnss_gns.so.2} exists on your system, it should have been created during the installation. - - @node Build instructions for Ubuntu 12.04 using Git @section Build instructions for Ubuntu 12.04 using Git @@ -673,7 +676,11 @@ After installing it, you need to create an empty configuration file: mkdir ~/.gnunet; touch ~/.gnunet/gnunet.conf @end example -And finally you can start GNUnet with @code{$ gnunet-arm -s}. +And finally you can start GNUnet with: + +@example +$ gnunet-arm -s +@end example @node Install the GNUnet-gtk user interface from Git @subsection Install the GNUnet-gtk user interface from Git @@ -714,9 +721,10 @@ $ make; sudo make install This document is a guide to building GNUnet and its dependencies on -Windows platforms. GNUnet development is mostly done under Linux and -especially SVN checkouts may not build out of the box. -We regret any inconvenience, and if you have problems, please report them. +Windows platforms. GNUnet development is mostly done under GNU/Linux and +especially git checkouts may not build out of the box. +We regret any inconvenience, and if you have problems, please report +them. @node Requirements @subsection Requirements @@ -728,8 +736,9 @@ The Howto is based upon a @strong{Windows Server 2008 32bit} is a convenient set of scripts which creates a working msys/mingw installation and installs most dependencies required for GNUnet. -As of the point of the creation of this Howto, GNUnet @strong{requires} a -Windows @strong{Server} 2003 or newer for full feature support. +As of the point of the creation of these instructions, +GNUnet @strong{requires} a Windows @strong{Server} 2003 or +newer for full feature support. Windows Vista and later will also work, but @strong{non-server version can not run a VPN-Exit-Node} as the NAT features have been removed as of Windows Vista. @@ -808,8 +817,8 @@ other one is /src which contains all the installation sources sbuild just compiled. @end itemize -Check out the current gnunet-sources (git HEAD) from the -gnunet-repository, we will do this in your home directory: +Check out the current GNUnet sources (git HEAD) from the +GNUnet repository "gnunet.git", we will do this in your home directory: @code{git clone https://gnunet.org/git/gnunet/ ~/gnunet} @@ -828,7 +837,7 @@ STRIP=true CPPFLAGS="-DUSE_IPV6=1 -DW32_VEH" CFLAGS="$CFLAGS -g -O2" \ --enable-silent-rules --enable-experimental 2>&1 | tee -a ./configure.log @end example -The parameters above will configure for a reasonable gnunet installation +The parameters above will configure for a reasonable GNUnet installation to the your msys-root directory. Depending on which features your would like to build or you may need to specify additional dependencies. Sbuild installed most libs into @@ -836,11 +845,11 @@ the /mingw subdirectory, so remember to prefix library locations with this path. Like on a unixoid system, you might want to use your home directory as -prefix for your own gnunet installation for development, without tainting +prefix for your own GNUnet installation for development, without tainting the buildenvironment. Just change the "prefix" parameter to point towards ~/ in this case. -Now it's time to compile gnunet as usual. Though this will take some time, +Now it's time to compile GNUnet as usual. Though this will take some time, so you may fetch yourself a coffee or some Mate now... @example @@ -851,22 +860,24 @@ make ; make install @subsection Adjusting Windows for running and testing GNUnet Assuming the build succeeded and you -@strong{added the bin directory of your gnunet to PATH}, you can now use +@strong{added the bin directory of your GNUnet to PATH}, you can now use your gnunet-installation as usual. Remember that UAC or the windows firewall may popup initially, blocking further execution of gnunet until you acknowledge them. -You will also have to take the usual steps to get p2p software running -properly (port forwarding, ...), and gnunet will require administrative -permissions as it may even install a device-driver (in case you are using -gnunet-vpn and/or gnunet-exit). +You will also have to take the usual steps to get peer-to-peer (p2p) +software running properly (port forwarding, ...), +and GNUnet will require administrative permissions as it may even +install a device-driver (in case you are using gnunet-vpn and/or +gnunet-exit). @node Building the GNUnet Installer @subsection Building the GNUnet Installer The GNUnet installer is made with -@uref{http://nsis.sourceforge.net/, NSIS} The installer script is located -in @file{contrib\win} in the GNUnet source tree. +@uref{http://nsis.sourceforge.net/, NSIS}. +The installer script is located in @file{contrib\win} in the +GNUnet source tree. @node Using GNUnet with Netbeans on Windows @subsection Using GNUnet with Netbeans on Windows @@ -1092,9 +1103,13 @@ performance and Postgres better resillience. @section Installing GNUnet from Git on Ubuntu 14.4 @strong{Install the required build tools:} -@code{ $ sudo apt-get install git automake autopoint autoconf } + +@example +$ sudo apt-get install git automake autopoint autoconf +@end example @strong{Install the required dependencies} + @example $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ @@ -1103,19 +1118,28 @@ $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ @strong{Choose one or more database backends} -SQLite3: +@itemize @bullet + +@item SQLite3: + @example $ sudo apt-get install libsqlite3-dev @end example -MySQL: + +@item MySQL: + @example $ sudo apt-get install libmysqlclient-dev @end example -PostgreSQL: + +@item PostgreSQL: + @example $ sudo apt-get install libpq-dev postgresql @end example +@end itemize + @strong{Install the optional dependencies for gnunet-conversation:} @example @@ -1123,11 +1147,17 @@ $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev @end example @strong{Install the libgrypt 1.6.1:} -For Ubuntu 14.04: + +@itemize @bullet + +@item For Ubuntu 14.04: + @example $ sudo apt-get install libgcrypt20-dev @end example -For Ubuntu older 14.04: + +@item For Ubuntu older 14.04: + @example $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 $ tar xf libgcrypt-1.6.1.tar.bz2 @@ -1136,7 +1166,11 @@ $ ./configure $ sudo make install $ cd .. @end example + +@end itemize + @strong{Install libgnurl} + @example $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 $ tar xf gnurl-7.35.0.tar.bz2 @@ -1153,6 +1187,7 @@ $ cd .. @end example @strong{Install GNUnet} + @example $ git clone https://gnunet.org/git/gnunet/ $ cd gnunet/ @@ -1160,12 +1195,14 @@ $ ./bootstrap @end example If you want to: + @itemize @bullet +@item Install to a different directory: -@item -Install to a different directory:@ - --prefix=PREFIX +@example +--prefix=PREFIX +@end example @item Have sudo permission, but do not want to compile as root: @@ -1203,6 +1240,7 @@ $ gnunet-arm -s @node Build instructions for Debian 8 @section Build instructions for Debian 8 +@c FIXME: I -> we These are the installation instructions for Debian 8. They were tested sing a fresh Debian 8 AMD64 installation without non-free software (no @@ -1330,7 +1368,8 @@ up-to-date instructions and should not be expected to work for GNUnet 0.10.x. A set of older installation instructions can also be found in the file @file{doc/outdated-and-old-installation-instructions.txt} in the -source of GNUnet. +source tree of GNUnet. + This file covers old instructions which no longer receive security updates or any kind of support. @@ -1346,49 +1385,55 @@ updates or any kind of support. @node Installing GNUnet 0.10.1 on Ubuntu 14.04 @subsection Installing GNUnet 0.10.1 on Ubuntu 14.04 -Install the required dependencies@ +Install the required dependencies: @example $ sudo apt-get install libltdl-dev libgpg-error-dev libidn11-dev \ - libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ - libmicrohttpd-dev libgnutls28-dev + libunistring-dev libglpk-dev libbluetooth-dev libextractor-dev \ + libmicrohttpd-dev libgnutls28-dev @end example -Choose one or more database backends@ -SQLite3@ +Choose one or more database backends: + +@itemize @bullet + +@item SQLite3 @example $ sudo apt-get install libsqlite3-dev@ @end example -MySQL@ +@item MySQL @example $ sudo apt-get install libmysqlclient-dev@ @end example -PostgreSQL@ +@item PostgreSQL @example $ sudo apt-get install libpq-dev postgresql@ @end example -Install the optional dependencies for gnunet-conversation:@ +@end itemize + +Install the optional dependencies for gnunet-conversation: @example - $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev@ + $ sudo apt-get install gstreamer1.0 libpulse-dev libopus-dev @end example -Install the libgcrypt 1.6: +Install libgcrypt 1.6: @itemize @bullet + @item For Ubuntu 14.04: @example $ sudo apt-get install libgcrypt20-dev @end example -@item For Ubuntu older 14.04: +@item For Ubuntu older than 14.04: @example wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.1.tar.bz2 @@ -1400,7 +1445,7 @@ $ cd .. @end example @end itemize -Install libgnurl@ +Install libgnurl: @example $ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2 @@ -1417,7 +1462,7 @@ $ sudo make install@ $ cd ..@ @end example -Install GNUnet@ +Install GNUnet: @example $ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz @@ -1478,32 +1523,31 @@ have to compile it from source: @itemize @bullet -@item -Download the latest version from http://ftp.gnu.org/gnu/glpk/ +@item Download the latest version from +@uref{http://ftp.gnu.org/gnu/glpk/} -@item -Unzip it using your favourite unzipper In the MSYS shell: +@item Unzip the downloaded source tarball using your favourite +unzipper application In the MSYS shell -@item -change to the respective directory +@item change to the respective directory -@item +@item Configure glpk for "i686-pc-mingw32": @example ./configure '--build=i686-pc-mingw32' @end example -@item -run +@item run @example make install check @end example -MinGW does not automatically detect the correct buildtype so you have to -specify it manually @end itemize +MinGW does not automatically detect the correct buildtype so you have to +specify it manually. + @node GUI build instructions for Ubuntu 12.04 using Subversion @subsection GUI build instructions for Ubuntu 12.04 using Subversion @@ -1517,32 +1561,29 @@ $ sudo apt-get install libgladeui-dev libqrencode-dev @end example Please ensure that the GNUnet shared libraries can be found by the linker. -If you installed GNUnet libraries in a non standard path (say -GNUNET_PREFIX=/usr/local/lib/), you can +If you installed GNUnet libraries in a non standard path +(say GNUNET_PREFIX=/usr/local/lib/), you can @itemize @bullet -@item -set the environmental variable permanently to +@item set the environmental variable permanently to: @example LD_LIBRARY_PATH=$GNUNET_PREFIX @end example -@item -or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} +@item or add @code{$GNUNET_PREFIX} to @file{/etc/ld.so.conf} @end itemize - -Now you can checkout and compile the GNUnet GUI tools@ +Now you can checkout and compile the GNUnet GUI tools: @example - $ git clone https://gnunet.org/git/gnunet-gtk - $ cd gnunet-gtk - $ ./bootstrap - $ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. - $ make install +$ git clone https://gnunet.org/git/gnunet-gtk +$ cd gnunet-gtk +$ ./bootstrap +$ ./configure --prefix=$GNUNET_PREFIX/.. --with-gnunet=$GNUNET_PREFIX/.. +$ make install @end example @c @node Installation with gnunet-update @@ -1633,9 +1674,9 @@ Now you can checkout and compile the GNUnet GUI tools@ @node Instructions for Microsoft Windows Platforms (Old) @subsection Instructions for Microsoft Windows Platforms (Old) -This document is a @b{DEPRECATED} installation guide for gnunet on +This document is a @b{DEPRECATED} installation guide for GNUnet on Windows. -It will not work for recent gnunet versions, but maybe it will be of +It will not work for recent GNUnet versions, but maybe it will be of some use if problems arise. The Windows build uses a UNIX emulator for Windows, @@ -1643,7 +1684,7 @@ The Windows build uses a UNIX emulator for Windows, These modules run natively on Windows and do not require additional emulation software besides the usual dependencies. -GNUnet development is mostly done under Linux and especially SVN +GNUnet development is mostly done under GNU/Linux and especially git checkouts may not build out of the box. We regret any inconvenience, and if you have problems, please report them. @@ -1660,17 +1701,14 @@ We regret any inconvenience, and if you have problems, please report them. @itemize @bullet -@item -Pentium II or equivalent processor, 350 MHz or better +@item Pentium II or equivalent processor, @geq{} 350 MHz -@item -128 MB RAM +@item 128 MB RAM -@item -600 MB free disk space +@item 600 MB free disk space + +@item Windows 2000 or Windows XP are recommended -@item -Windows 2000 or Windows XP are recommended @end itemize @node Software installation @@ -1680,18 +1718,20 @@ Windows 2000 or Windows XP are recommended @item @strong{Compression software}@ -@ + The software packages GNUnet depends on are usually compressed using UNIX -tools like tar, gzip and bzip2. +tools like @command{tar}, @command{gzip}, @command{xzip} and +@command{bzip2}. If you do not already have an utility that is able to extract such archives, get @uref{http://www.7-zip.org/, 7-Zip}. @item @strong{UNIX environment}@ -@ + The MinGW project provides the compiler toolchain that is used to build -GNUnet.@ Get the following packages from -@uref{http://sourceforge.net/projects/mingw/files/, the MinGW project}: +GNUnet. +Get the following packages from the +@uref{http://sourceforge.net/projects/mingw/files/, MinGW} project: @itemize @bullet @@ -1713,20 +1753,18 @@ GNUnet.@ Get the following packages from @itemize @bullet -@item -Install MSYS (to c:\mingw, for example.)@ +@item Install MSYS (to c:\mingw, for example.)@ Do @strong{not} use spaces in the pathname. For example, avoid a location such as @file{c:\program files\mingw}. -@item -Install MinGW runtime, utilities and GCC to a subdirectory -(to c:\mingw\mingw, for example) +@item Install MinGW runtime, utilities and GCC to a subdirectory +(to @file{c:\mingw\mingw}, for example) -@item -Install the Development Kit to the MSYS directory (c:\mingw) +@item Install the Development Kit to the MSYS directory +(@file{c:\mingw}) -@item -Create a batch file bash.bat in your MSYS directory with the files:@ +@item Create a batch file bash.bat in your MSYS directory with +the files: @example bin\sh.exe --login @@ -1734,101 +1772,78 @@ bin\sh.exe --login This batch file opens a shell which is used to invoke the build processes. -MinGW's standard shell (msys.bat) is not suitable because it opens a -separate console window. -On Vista, bash.bat needs to be run as administrator. +MinGW's standard shell (@command{msys.bat}) is not suitable +because it opens a separate console window. +On Vista, @command{bash.bat} needs to be run as Administrator. @item -Start bash.sh and rename (c:\mingw\mingw\)lib\libstdc++.la to avoid -problems: +Start @command{bash.sh} and rename +@file{c:\mingw\mingw\lib\libstdc++.la} to avoid problems: @example mv /usr/mingw/lib/libstdc++.la /usr/mingw/lib/libstdc++.la.broken @end example @item -Unpack the Windows API to the MinGW directory (c:\mingw\mingw\) and +Unpack the Windows API to the MinGW directory (@file{c:\mingw\mingw\}) and remove the declaration of DATADIR from -(c:\mingw\mingw\)include\objidl.h (lines 55-58) +(@file{c:\mingw\mingw\include\objidl.h} (lines 55-58) @item -Unpack autoconf, automake to the MSYS directory (c:\mingw) +Unpack autoconf, automake to the MSYS directory (@file{c:\mingw}) @item -Install all other packages to the MinGW directory (c:\mingw\mingw\) +Install all other packages to the MinGW directory (@file{c:\mingw\mingw\}) @end itemize -@item -@strong{GNU Libtool}@ -@ -GNU Libtool is required to use shared libraries.@ -@ -Get the prebuilt package from here and unpack it to the MinGW directory -(c:\mingw) +@item @strong{GNU Libtool}@ +GNU Libtool is required to use shared libraries. +Get the prebuilt package from here and unpack it to the +MinGW directory (@file{c:\mingw}) -@item -@strong{Pthreads}@ -@ -GNUnet uses the portable POSIX thread library for multi-threading..@ +@item @strong{Pthreads}@ +GNUnet uses the portable POSIX thread library for multi-threading: @itemize @bullet - -@item -Save +@item Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/libpthreadGC2.a, libpthreadGC2.a} (x86) or @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/libpthreadGC2.a, libpthreadGC2.a} (x64) as libpthread.a into the @file{lib} directory (@file{c:\mingw\mingw\lib\libpthread.a}). -@item -Save +@item Save @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x86/pthreadGC2.dll, pthreadGC2.dll} (x86) or @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/x64/pthreadGC2.dll, libpthreadGC2.a} (x64) into the MinGW @file{bin} directory (@file{c:\mingw\mingw\bin}). -@item -Download all header files from +@item Download all header files from @uref{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/include/, include/} to the @file{include} directory (@file{c:\mingw\mingw\include}). @end itemize -@item -@strong{GNU MP@ -}@ -@ +@item @strong{GNU MP}@ GNUnet uses the GNU Multiple Precision library for special cryptographic -operations.@ -@ -Get the GMP binary package from the +operations. Get the GMP binary package from the @uref{http://sourceforge.net/projects/mingwrep/, MinGW repository} and -unpack it to the MinGW directory (c:\mingw\mingw) +unpack it to the MinGW directory (@file{c:\mingw\mingw}) -@item -@strong{GNU Gettext}@ -@ -GNU gettext is used to provide national language support.@ -@ +@item @strong{GNU Gettext}@ +GNU gettext is used to provide national language support. Get the prebuilt package from hereand unpack it to the MinGW -directory (c:\mingw\mingw) +directory (@file{c:\mingw\mingw}) -@item -@strong{GNU iconv}@ -@ -GNU Libiconv is used for character encoding conversion.@ -@ +@item @strong{GNU iconv}@ +GNU Libiconv is used for character encoding conversion. Get the prebuilt package from here and unpack it to the MinGW -directory (c:\mingw\mingw) +directory (@file{c:\mingw\mingw}). -@item -@strong{SQLite}@ -@ -GNUnet uses the SQLite database to store data.@ -@ +@item @strong{SQLite}@ +GNUnet uses the SQLite database to store data. Get the prebuilt binary from here and unpack it to your MinGW directory. @item @strong{MySQL}@ @@ -1838,12 +1853,13 @@ As an alternative to SQLite, GNUnet also supports MySQL. @item Get the binary installer from the @uref{http://dev.mysql.com/downloads/mysql/4.1.html#Windows, MySQL project} -(version 4.1), install it and follow the instructions in README.mysql. +(version 4.1), install it and follow the instructions in +@file{README.mysql}. -@item Create a temporary build directory (c:\mysql) +@item Create a temporary build directory (@file{c:\mysql}) -@item Copy the directories include\ and lib\ from the MySQL directory to -the new directory +@item Copy the directories @file{include\} and @file{lib\} from the +MySQL directory to the new directory @item Get the patches from @uref{http://bugs.mysql.com/bug.php?id=8906&files=1, Bug #8906} and @@ -1854,130 +1870,112 @@ latter is only required for MySQL patch -p 0 @end example -@item Move lib\opt\libmysql.dll to lib\libmysql.dll +@item Move @file{lib\opt\libmysql.dll} to @file{lib\libmysql.dll} -@item Change to lib\ and create an import library:@ +@item Change to @file{lib\} and create an import library: @example -dlltool --input-def ../include/libmySQL.def --dllname libmysql.dll - --output-lib libmysqlclient.a -k +dlltool --input-def ../include/libmySQL.def \ +--dllname libmysql.dll \ +--output-lib libmysqlclient.a -k @end example @item Copy include\* to include\mysql\ -@item Pass "--with-mysql=/c/mysql" to ./configure and copy libmysql.dll +@item Pass "@code{--with-mysql=/c/mysql}" to +@command{./configure} and copy @file{libmysql.dll} to your PATH or GNUnet's @file{bin} directory @end itemize -@item -@strong{GTK+}@ -@ -gnunet-gtk and libextractor depend on GTK.@ -@ -Get the the binary and developer packages of atk, glib, gtk, iconv, -gettext-runtime, pango from -@uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack it to the -MinGW directory (c:\mingw\mingw)@ -@ -Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and libpng -and unpack them to the MinGW directory (c:\mingw\mingw)@ -@ -Here is an all-in-one package for +@item @strong{GTK+}@ +@command{gnunet-gtk} and @command{libextractor} depend on GTK. +Get the the binary and developer packages of @command{atk}, +@command{glib}, @command{gtk}, @command{iconv}, +@command{gettext-runtime}, @command{pango} from +@uref{ftp://ftp.gtk.org/pub/gtk/v2.6/win32, gtk.org} and unpack them +to the MinGW directory (@file{c:\mingw\mingw}). +@c FIXME: The URL below for pkg-config seems wrong. +Get @uref{http://www.gtk.org/download/win32.php, pkg-config} and +@command{libpng} and unpack them to the MinGW directory +(@file{c:\mingw\mingw}). +Here is an all-in-one package for the @uref{http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip, gtk+dependencies} . Do not overwrite any existing files! -@item -@strong{Glade}@ -@ -gnunet-gtk and and gnunet-setup were created using this interface builder +@item @strong{Glade}@ +@command{gnunet-gtk} and @command{gnunet-setup} were created using +this interface builder @itemize @bullet +@item Get the Glade and libglade (-bin and -devel) packages +(without GTK!) from +@uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack them to +the MinGW directory (@file{c:\mingw\mingw}). -@item -Get the Glade and libglade (-bin and -devel) packages (without GTK!) from -@uref{http://gladewin32.sourceforge.net/, GladeWin32} and unpack it to -the MinGW directory (c:\mingw\mingw) - -@item -Get libxml from here and unpack it to the MinGW -directory (c:\mingw\mingw). +@item Get @command{libxml} from here and unpack it to the MinGW +directory (@file{c:\mingw\mingw}). @end itemize - -@item -@strong{zLib}@ -@ -libextractor requires zLib to decompress some file formats. GNUnet uses it -to (de)compress meta-data.@ -@ -Get zLib from here (Signature) and unpack it to the -MinGW directory (c:\mingw\mingw) - -@item -@strong{Bzip2}@ -@ -libextractor also requires Bzip2 to decompress some file formats.@ -@ -Get Bzip2 (binary and developer package) from +@c FIXME: URLs +@item @strong{zLib}@ +@command{libextractor} requires @command{zLib} to decompress some file +formats. GNUnet uses it to (de)compress meta-data. +Get zLib from here (Signature) and unpack it to the MinGW directory +(@file{c:\mingw\mingw}). + +@item @strong{Bzip2}@ +@command{libextractor} also requires @command{Bzip2} to +decompress some file formats. +Get the Bzip2 (binary and developer package) from @uref{http://gnuwin32.sourceforge.net/packages/bzip2.htm, GnuWin32} and -unpack it to the MinGW directory (c:\mingw\mingw) +unpack it to the MinGW directory (@file{c:\mingw\mingw}). -@item -@strong{Libgcrypt}@ -@ -Libgcrypt provides the cryptographic functions used by GNUnet@ -@ +@item @strong{Libgcrypt}@ +@command{Libgcrypt} provides the cryptographic functions used by GNUnet. Get Libgcrypt from @uref{ftp://ftp.gnupg.org/gcrypt/libgcrypt/, here}, -compile and place it in the MinGW directory (c:\mingw\mingw). Currently -you need at least version 1.4.2 to compile GNUnet. +compile and place it in the MinGW directory +(@file{c:\mingw\mingw}). Currently libgcrypt @geq{} 1.4.2 is required to +compile GNUnet. -@item -@strong{PlibC}@ -@ -PlibC emulates Unix functions under Windows.@ -@ -Get PlibC from here and unpack it to the MinGW -directory (c:\mingw\mingw) +@item @strong{PlibC}@ +PlibC emulates Unix functions under Windows. Get PlibC from here and +unpack it to the MinGW directory (c:\mingw\mingw) -@item -@strong{OGG Vorbis}@ -@ -OGG Vorbis is used to extract meta-data from .ogg files@ -@ +@item @strong{OGG Vorbis}@ +@command{OGG Vorbis} is used to extract meta-data from @file{.ogg} files. Get the packages @uref{http://www.gnunet.org/libextractor/download/win/libogg-1.1.4.zip, libogg} and @uref{http://www.gnunet.org/libextractor/download/win/libvorbis-1.2.3.zip, libvorbis} from the @uref{http://ftp.gnu.org/gnu/libextractor/libextractor-w32-1.0.0.zip, libextractor win32 build} -and unpack them to the MinGW directory (c:\mingw\mingw) +and unpack them to the MinGW directory (c:\mingw\mingw). -@item -@strong{Exiv2}@ -@ -(lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data@ -@ +@item @strong{Exiv2}@ +(lib)Exiv2 is used to extract meta-data from files with Exiv2 meta-data. Download @uref{http://www.gnunet.org/libextractor/download/win/exiv2-0.18.2.zip, Exiv2} -and unpack it to the MSYS directory (c:\mingw) +and unpack it to the MSYS directory (c:\mingw). @end itemize @node Building libextractor and GNUnet @subsubsection Building libextractor and GNUnet -Before you compile libextractor or GNUnet, be sure to set PKG_CONFIG_PATH: +Before you compile @command{libextractor} or @command{GNUnet}, +be sure to set @code{PKG_CONFIG_PATH}: @example export PKG_CONFIG_PATH=/mingw/lib/pkgconfig @end example @noindent -See Installation for basic instructions on building libextractor -and GNUnet. By default, all modules that are created in this way contain -debug information and are quite large. To compile release versions (small -and fast) set the variable CFLAGS: +@xref{GNUnet Installation Handbook} for basic instructions on building +@command{libextractor} and @command{GNUnet}. +By default, all modules that are created in this way contain +debug information and are quite large. To compile release versions +(small and fast) set the variable @code{CFLAGS}: @example export CFLAGS='-O2 -march=pentium -fomit-frame-pointer' @@ -1994,79 +1992,80 @@ located in @file{contrib\win} in the GNUnet source tree. @node Source @subsubsection Source +@c FIXME: URL The sources of all dependencies are available here. -@node Portable GNUnet -@section Portable GNUnet +@c @node Portable GNUnet +@c @section Portable GNUnet -Quick instructions on how to use the most recent GNUnet on most GNU/Linux -distributions +@c Quick instructions on how to use the most recent GNUnet on most GNU/Linux +@c distributions -Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian -and CentOS 6, but it should work on almost any GNU/Linux distribution. -More in-detail information can be found in the handbook. +@c Currently this has only been tested on Ubuntu 12.04, 12.10, 13.04, Debian +@c and CentOS 6, but it should work on almost any GNU/Linux distribution. +@c More in-detail information can be found in the handbook. -Note 2017-10: Currently this section assumes the old SVN repo of GNUnet -which no longer exists. +@c Note 2017-10: Currently this section assumes the old SVN repo of GNUnet +@c which no longer exists. -@menu -* Prerequisites:: -* Download & set up gnunet-update:: -* Install GNUnet:: -@end menu +@c @menu +@c * Prerequisites:: +@c * Download & set up gnunet-update:: +@c * Install GNUnet:: +@c @end menu -@node Prerequisites -@subsection Prerequisites +@c @node Prerequisites +@c @subsection Prerequisites -Open a terminal and paste this line into it to install all required tools -needed: +@c Open a terminal and paste this line into it to install all required tools +@c needed: -@example -sudo apt-get install python-gpgme subversion -@end example +@c @example +@c sudo apt-get install python-gpgme subversion +@c @end example -@node Download & set up gnunet-update -@subsection Download & set up gnunet-update +@c @node Download & set up gnunet-update +@c @subsection Download & set up gnunet-update -The following command will download a working version of gnunet-update -with the subversion tool and import the public key which is needed for -authentication: +@c The following command will download a working version of gnunet-update +@c with the subversion tool and import the public key which is needed for +@c authentication: -@example -svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update -cd ~/gnunet-update -gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 -@end example +@c @example +@c svn checkout -r24905 https://gnunet.org/svn/gnunet-update ~/gnunet-update +@c cd ~/gnunet-update +@c gpg --keyserver "hkp://keys.gnupg.net" --recv-keys 7C613D78 +@c @end example -@node Install GNUnet -@subsection Install GNUnet +@c @node Install GNUnet +@c @subsection Install GNUnet -Download and install GNUnet binaries which can be found here and set -library paths: +@c Download and install GNUnet binaries which can be found here and set +@c library paths: -@example -wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz -./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~ -echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment -echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \ - /etc/ld.so.conf.d/gnunet.conf > /dev/null -sudo ldconfig -@end example +@c @example +@c wget -P /tmp https://gnunet.org/install/packs/gnunet-0.9.4-`uname -m`.tgz +@c ./bin/gnunet-update install /tmp/gnunet-0.9*.tgz ~ +@c echo "PATH DEFAULT=$@{PATH@}:$HOME/bin" >> ~/.pam_environment +@c echo -e "$@{HOME@}/lib\n$@{HOME@}/lib/gnunet-deps" | sudo tee \ +@c /etc/ld.so.conf.d/gnunet.conf > /dev/null +@c sudo ldconfig +@c @end example -You may need to re-login once after executing these last commands +@c You may need to re-login once after executing these last commands -That's it, GNUnet is installed in your home directory now. GNUnet can be -configured and afterwards started by executing: +@c That's it, GNUnet is installed in your home directory now. GNUnet can be +@c configured and afterwards started by executing: -@example -gnunet-arm -s -@end example +@c @example +@c gnunet-arm -s +@c @end example @node The graphical configuration interface @section The graphical configuration interface -If you also would like to use gnunet-gtk and gnunet-setup (highly -recommended for beginners), do: +If you also would like to use @command{gnunet-gtk} and +@command{gnunet-setup} (highly recommended for beginners), do: @example wget -P /tmp \ @@ -2075,7 +2074,7 @@ sh ~/gnunet-update/bin/gnunet-update install /tmp/gnunet-*gtk*.tgz ~ sudo ldconfig @end example -Now you can run @code{gnunet-setup} for easy configuration of your +Now you can run @command{gnunet-setup} for easy configuration of your GNUnet peer. @menu @@ -2117,43 +2116,52 @@ GNUnet peer. This chapter will describe the various configuration options in GNUnet. -The easiest way to configure your peer is to use the gnunet-setup tool. -gnunet-setup is part of the gnunet-gtk download. You might have to -install it separately. +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 gnunet-setup to help you while using the setup tool. +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. +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. In standard "peer-to-peer" -mode, your peer will connect to any peer. In the pure "friend-to-friend" +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. -Finally, in mixed mode, GNUnet will only connect to arbitrary peers if it +@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 modes, you first need to create a file -with the peer identities of your friends. Ask your friends to run +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 output of this command needs to be added to your friends file, which -is simply a plain text file with one line per friend with the output from -the above command. +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 friends file in the "FRIENDS" -option of the "topology" section. +You then specify the location of your @file{friends} file in the +"FRIENDS" option of the "topology" section. -Once you have created the friends file, you can tell GNUnet to only +Once you have created the @file{friends} file, you can tell GNUnet to only connect to your friends by setting the "FRIENDS-ONLY" option (again in the "topology" section) to YES. @@ -2162,7 +2170,8 @@ minimum number of friends to have (before connecting to arbitrary peers) under the "MINIMUM-FRIENDS" option. If you want to operate in normal P2P-only mode, simply set -"MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO. This is the default. +"MINIMUM-FRIENDS" to zero and "FRIENDS_ONLY" to NO. +This is the default. @node Configuring the hostlist to bootstrap @subsection Configuring the hostlist to bootstrap @@ -2174,13 +2183,13 @@ 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. +"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 your configuration file and edit the -@code{[hostlist]}-section. You have to set the argument "-b" in the +To activate bootstrapping, edit the @code{[hostlist]}-section in your +configuration file. You have to set the argument "-b" in the options line: @example @@ -2225,8 +2234,8 @@ OPTIONS = -b -e @end example @noindent -Furthermore you can specify in which file the lists are saved. To save the -lists in the file "hostlists.file" just add the line: +Furthermore you can specify in which file the lists are saved. +To save the lists in the file "hostlists.file" just add the line: @example HOSTLISTFILE = hostlists.file @@ -2262,17 +2271,19 @@ The hostlist client supports the following proxy types at the moment: In addition authentication at the proxy with username and password can be configured. -To configure proxy support for the hostlist client in the gnunet-setup -tool, select the "hostlist" tab and select the appropriate proxy type. +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 these information will be stored in the configuration in -plain text. +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 configure these options directly in the configuration, you can -configure the following settings in the @code{[hostlist]} -section of the configuration: +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, @@ -2296,7 +2307,7 @@ your peer to act as a hostlist server, providing other peers the list of peers known to him. Yor server can act as a bootstrap server and peers needing to obtain a -list of peers can contact him to download this list. +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 libcurl and microhttpd support. How you build your peer with this options can be found here: @@ -2305,7 +2316,8 @@ support. How you build your peer with this options can be found here: To configure your peer to act as a bootstrap server you have to add the "@code{-p}" option to 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: +the http server. +In conclusion you have to add the following lines: @example [hostlist] @@ -2334,11 +2346,12 @@ OPTIONS = -p -a @noindent With this configuration your peer will a act as a bootstrap server and -advertise this hostlist to other peers connecting to him. The URL used to -download the list will be +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 not human readable, so you should not try to download it using your webbrowser. Just point your GNUnet peer to the @@ -2376,8 +2389,8 @@ We are generally testing the code against MySQL 5.1 at this point. @itemize @bullet -@item -On up-to-date hardware where mysql can be used comfortably, this module +@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). @@ -2397,9 +2410,11 @@ inconsistencies. Some of the other databases do not support repair. @subsection Setup Instructions @itemize @bullet + @item In @code{gnunet.conf} set in section "DATASTORE" the value for "DATABASE" to "mysql". -@item Access mysql as root:@ + +@item Access mysql as root: @example $ mysql -u root -p @@ -2418,7 +2433,7 @@ FLUSH PRIVILEGES; @end example @item -In the $HOME directory of $USER, create a ".my.cnf" file with the +In the $HOME directory of $USER, create a "@file{.my.cnf}" file with the following lines @example @@ -2429,9 +2444,10 @@ password=$the_password_you_like @end itemize -Thats it. Note that @code{.my.cnf} file is a slight security risk unless -its on a safe partition. The $HOME/.my.cnf can of course be a symbolic -link. Luckily $USER has only priviledges to mess up GNUnet's tables, +Thats it. Note that @file{.my.cnf} file is a slight security risk unless +its on a safe partition. The @file{$HOME/.my.cnf} can of course be +a symbolic link. +Luckily $USER has only priviledges to mess up GNUnet's tables, which should be pretty harmless. @node Testing @@ -2449,8 +2465,12 @@ mysql> use gnunet; If you get the message "Database changed" it probably works. If you get "ERROR 2002: Can't connect to local MySQL server@ -through socket '/tmp/mysql.sock' (2)" it may be resolvable by@ -"ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock"@ +through socket '/tmp/mysql.sock' (2)" it may be resolvable by + +@example +ln -s /var/run/mysqld/mysqld.sock /tmp/mysql.sock +@end example + so there may be some additional trouble depending on your mysql setup. @node Performance Tuning @@ -2536,7 +2556,7 @@ where $GNUNET_USER is the name of the user running GNUnet.@ @item -As that user (so typically as user "gnunet"), create a database (or two):@ +As that user (so typically as user "gnunet"), create a database (or two): @example $ createdb gnunet @@ -2552,7 +2572,7 @@ Now you should be able to start @code{gnunet-arm}. @subsection Testing the setup manually You may want to try if the database connection works. First, again login -as the user who will run gnunet-arm. Then use, +as the user who will run @command{gnunet-arm}. Then use: @example $ psql gnunet # or gnunetcheck @@ -2560,7 +2580,7 @@ gnunet=> \dt @end example @noindent -If, after you have started gnunet-arm at least once, you get +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 @@ -2618,12 +2638,14 @@ strength of the adversary). @subsection Configuring logging Logging in GNUnet 0.9.0 is controlled via the "-L" and "-l" options. -Using "-L", a log level can be specified. With log level "ERROR" only -serious errors are logged. -The default log level is "WARNING" which causes anything of -concern to be logged. Log level "INFO" can be used to log anything that -might be interesting information whereas "DEBUG" can be used by -developers to log debugging messages (but you need to run configure with +Using "-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 "-l" option is used to specify the log file. @@ -2772,8 +2794,8 @@ TESTING_IGNORE_KEYS = ACCEPT_FROM; @item transport-wlan -There is a special article how to setup the WLAN plugin, so here only the -settings. Just specify the interface to use: +The next section describes how to setup the WLAN plugin, +so here only the settings. Just specify the interface to use: @example [transport-wlan] @@ -2788,13 +2810,12 @@ TESTING_IGNORE_KEYS = ACCEPT_FROM; @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 -the GNUnet where no internet access is possible, for example while -catastrophes or when censorship cuts you off the internet. +GNUnet where no internet access is possible, for example during +catastrophes or when censorship cuts you off from the internet. @menu @@ -2843,8 +2864,9 @@ TESTMODE = 0 @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: +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 @@ -3046,27 +3068,27 @@ 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 +your configuration containing the peer id of the peer to blacklist and the plugin@ if required. -Examples:@ +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@ +[transport-blacklist AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = tcp @end example To blacklist connections to P565... on peer AG2P... using all plugins add: @example -[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520]@ -P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G =@ +[transport-blacklist-AG2PHES1BARB9IJCPAMJTFPVJ5V3A72S3F2A8SBUB8DAQ2V0O3V8G6G2JU56FHGFOHMQVKBSQFV98TCGTC3RJ1NINP82G0RC00N1520] +P565723JO1C2HSN6J29TAQ22MN6CI8HTMUU55T0FUQG4CMDGGEQ8UCNBKUMB94GC8R9G4FB2SF9LDOBAJ6AMINBP4JHHDD6L7VD801G = @end example -You can also add a blacklist client usign the blacklist api. On a +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. @@ -3084,12 +3106,12 @@ On blacklist check for (peer, plugin) @node Configuration of the HTTP and HTTPS transport plugins @subsection Configuration of the HTTP and HTTPS transport plugins -The client part of the http and https transport plugins can be configured +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. -The both the HTTP and HTTPS clients support the following proxy types at +Both the HTTP and HTTPS clients support the following proxy types at the moment: @itemize @bullet @@ -3109,8 +3131,8 @@ and "Proxy password" boxes. Be aware that these information will be stored in the configuration in plain text. To configure these options directly in the configuration, you can -configure the following settings in the [transport-http_client] and -[transport-https_client] section of the configuration: +configure the following settings in the @code{[transport-http_client]} +and @code{[transport-https_client]} section of the configuration: @example # Type of proxy server, @@ -3170,7 +3192,7 @@ First of all, GNS needs to be integrated with the operating system. Most of this section is about the operating system level integration. Additionally, each individual user who wants to use the system must also -initialize his GNS zones. This can be done by running (after starting +initialize their GNS zones. This can be done by running (after starting GNUnet) @example @@ -3221,10 +3243,12 @@ sections. @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 system administrator usually configures the operating system's name -services using the file @file{/etc/nsswitch.conf}. +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. @@ -3237,8 +3261,8 @@ To use the GNS NSS plugin you have to either Name resolution is controlled by the @emph{hosts} section in the NSS configuration. By default this section first performs a lookup in the -/etc/hosts file and then in DNS. The nsswitch file should contain a line -similar to: +@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 @@ -3354,9 +3378,28 @@ 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 not work with libcurl compiled +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 @@ -3378,7 +3421,8 @@ $ gnunet-gns-proxy @noindent Configure your browser to use this SOCKSv5 proxy on port 7777 and visit this link. -If you use firefox you also have to go to about:config and set the key +If you use @command{Firefox} (or one of its deriviates/forks such as +Icecat) you also have to go to @code{about:config} and set the key @code{network.proxy.socks_remote_dns} to @code{true}. When you visit @code{https://homepage.gnu/}, you should get to the @@ -3386,7 +3430,8 @@ When you visit @code{https://homepage.gnu/}, you should get to the configured proxy) should give you a valid SSL certificate for @code{homepage.gnu} and no warnings. It should look like this: -@c insert image here gnunethpgns.png +@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 Automatic Shortening in the GNU Name System @subsubsection Automatic Shortening in the GNU Name System @@ -3424,12 +3469,14 @@ applied. 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. - -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 +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. @@ -3441,24 +3488,24 @@ The other options as shown on the gnunet-setup tool are: 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 10.0.0.1/255.255.0.0 already, you might use -10.1.0.1/255.255.0.0. -If you use 10.0.0.1/255.0.0.0 already, then you might use -192.168.0.1/255.255.0.0. +if 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 (255.255.0.0 -or, even better, 255.0.0.0) to allow more mappings of remote IP Addresses -into this range. -However, even a 255.255.255.0-mask will suffice for most users. +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 "fe80:"). -A subnet Unique Local Unicast (fd00::/8-prefix) that you are currently -not using would be a good choice. +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 @@ -3779,10 +3826,10 @@ 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 -@code{/etc/gnunet.conf} and ignore options set by individual users. +@file{/etc/gnunet.conf} and ignore options set by individual users. Again, each user should then start the peer using -@code{gnunet-arm -s} --- and strongly consider adding logic to start +@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) @@ -3944,5 +3991,5 @@ 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 -"--with-gnunetdns=GRPNAME" configure option. +@code{--with-gnunetdns=GRPNAME} configure option. diff --git a/doc/documentation/chapters/philosophy.texi b/doc/documentation/chapters/philosophy.texi index 3ebdf473e..10006ebe1 100644 --- a/doc/documentation/chapters/philosophy.texi +++ b/doc/documentation/chapters/philosophy.texi @@ -1,3 +1,4 @@ +@cindex Philosopy @node Philosophy @chapter Philosophy @@ -21,7 +22,7 @@ generation of decentralized Internet protocols. * Key Concepts:: @end menu - +@cindex Design Goals @cindex Design Goals @node Design Goals @section Design Goals @@ -258,6 +259,7 @@ imposes no minimal requirements on cover traffic. It is possible to forego anonymity when this is not required. The anonymity level of 0 allows GNUnet to use more efficient, non-anonymous routing. +@cindex How file-sharing achieves Anonymity @node How file-sharing achieves Anonymity @subsubsection How file-sharing achieves Anonymity @@ -299,7 +301,8 @@ GNUnet we do not have to indirect the replies if we don't think we need more traffic to hide our own actions. This increases the efficiency of the network as we can indirect less under -higher load.@footnote{More details can be found in @uref{https://gnunet.org/gap, this paper}} +higher load.@footnote{More details can be found in +@uref{https://gnunet.org/gap, this paper}} @cindex Deniability @node Deniability @@ -333,8 +336,12 @@ generated along with a private key the peer is started for the first time. While the identity is binary data, it is often expressed as ASCII string. For example, the following is a peer identity as you might see it in various places: -@code{ UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0} +@example +UAT1S6PMPITLBKSJ2DGV341JI6KF7B66AC4JVCN9811NNEGQLUN0 +@end example + +@noindent You can find your peer identity by running @command{gnunet-peerinfo -s}. @cindex GNS Zones @@ -365,7 +372,7 @@ public key first. @subsection Egos Egos are your "identities" in GNUnet. Any user can assume multiple -identities, for example to separate his activities online. Egos can +identities, for example to separate teir activities online. Egos can correspond to pseudonyms or real-world identities. Technically, an ego is first of all a public-private key pair. diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi index 6222cf314..2497d4b09 100644 --- a/doc/documentation/gnunet.texi +++ b/doc/documentation/gnunet.texi @@ -111,6 +111,7 @@ in the respective authors file or section, please do let us know. * Vocabulary:: Vocabulary * GNUnet Installation Handbook:: How to install GNUnet * Using GNUnet:: Using GNUnet +* Configuration Handbook:: Configuring GNUnet * GNUnet Developer Handbook:: Developing GNUnet * GNU Free Documentation License:: The license of this manual. * GNU General Public License:: The license of this manual. @@ -154,10 +155,12 @@ GNUnet Installation Handbook * Installing GNUnet from Git on Ubuntu 14.4:: * Build instructions for Debian 8:: * Outdated build instructions for previous revisions:: -* Portable GNUnet:: +@c * Portable GNUnet:: * The graphical configuration interface:: * How to start and stop a GNUnet peer:: +Configuration Handbook + Using GNUnet * Checking the Installation:: @@ -225,6 +228,8 @@ GNUnet Developer Handbook @include chapters/user.texi @c ********************************************************************* +@include chapters/configuration.texi + @c ********************************************************************* @include chapters/developer.texi @c @include gnunet-c-tutorial.texi -- 2.25.1