@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
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::
@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
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
@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
@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
(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
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
@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
Here you can find some rules to help you write code for GNUnet.
-
-
@c ***********************************************************************
@menu
* Naming conventions::
@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 ***********************************************************************
@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 ***********************************************************************
@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 ***********************************************************************
@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
@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 ***********************************************************************
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
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:
@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
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.
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).
"UNIT"); @}
@end example
-
Where:
@table @asis
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.
@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
@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.
@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.
@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
(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
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.
(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
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
* 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
$ make
$ sudo make install
$ cd ..
-$ sudo ldconfig # just to be safe
+# just to be safe run this:
+$ sudo ldconfig
@end example
@noindent
@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
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
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
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.
/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}
--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
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
@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
@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 \
@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
@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
$ 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
@end example
@strong{Install GNUnet}
+
@example
$ git clone https://gnunet.org/git/gnunet/
$ cd gnunet/
@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:
@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
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.
@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
@end example
@end itemize
-Install libgnurl@
+Install libgnurl:
@example
$ wget https://gnunet.org/sites/default/files/gnurl-7.35.0.tar.bz2
$ cd ..@
@end example
-Install GNUnet@
+Install GNUnet:
@example
$ wget http://ftpmirror.gnu.org/gnunet/gnunet-0.10.1.tar.gz
@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
@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
@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,
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.
@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
@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
@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
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}@
@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
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'
@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 \
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
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.
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
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
@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
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,
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:
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]
@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
@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).
@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
@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
@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
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
@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
@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
@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
@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.
@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]
@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
@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
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.
@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
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,
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
@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.
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
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
@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
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
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.
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
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)
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.
projects / oweals / gnunet.git / commitdiff