any questions or problems! Check here how to contact the GNUnet
team: @uref{https://gnunet.org/contact_information}
-
+@node Installing GNUnet
@section Installing GNUnet
First of all you have to install a current version of GNUnet. You can download a
can fail. You should only use the development version if you know that you require a
certain feature or a certain issue has been fixed since the last release.
+@node Obtaining a stable version
@subsection Obtaining a stable version
You can download the latest stable version of GNUnet from GNU FTP mirrors:
However, please note that stable versions can be very outdated, as a developer
you are strongly encouraged to use the version from @uref{https://gnunet.org/git/}.
+@node Installing Build Tool Chain and Dependencies
@subsection Installing Build Tool Chain and Dependencies
To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies.
For the filesharing service you should install at least one of the datastore backends mysql,
sqlite or postgresql.
+@node Obtaining the latest version from Git
@subsection Obtaining the latest version from Git
The latest development version can obtained from our Git repository. To obtain
The remainder of this tutorial assumes that you have Git branch ``master'' checked out.
+@node Compiling and Installing GNUnet
@subsection Compiling and Installing GNUnet
First, you need to install at least libgnupgerror version 1.27
$ cd ..
@end example
+@node Installing GNUnet
@subsubsection Installing GNUnet
Assuming all dependencies are installed, the following commands will
compile and install GNUnet in your home directory. You can specify the
$ touch ~/.config/gnunet.conf
@end example
+@node Common Issues - Check your GNUnet installation
@subsection Common Issues - Check your GNUnet installation
You should check your installation to ensure that installing GNUnet
=============
@end example
+@node Background: GNUnet Architecture
@section Background: GNUnet Architecture
GNUnet is organized in layers and services. Each service is composed of a
clients communicate via a message protocol to be defined and implemented by
the programmer.
-
+@node First Steps with GNUnet
@section First Steps with GNUnet
+@node Configure your peer
@subsection Configure your peer
First of all we need to configure your peer. Each peer is started with a configuration
SERVERS = # prevent bootstrapping
@end example
+@node Start a peer
@subsection Start a peer
Each GNUnet instance (called peer) has an identity (peer ID) based on a
cryptographic public private key pair. The peer ID is the printable hash of the
I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
@end example
-
+@node Monitor a peer
@subsection Monitor a peer
In this section, we will monitor the behaviour of our peer's DHT service with respect to a
$ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service
@end example
-
+@node Starting Two Peers by Hand
@subsection Starting Two Peers by Hand
This section describes how to start two peers on the same machine by hand.
In practice, you might prefer the automated method
(@pxref{Starting Peers Using the Testbed Service}).
+@node Setup a second peer
@subsubsection Setup a second peer
We will now start a second peer on your machine.
For the second peer, you will need to manually create a modified
gnunet-peerinfo output for the first peer (otherwise you made an
error in the configuration).
+@node Start the second peer and connect the peers
@subsubsection Start the second peer and connect the peers
Then, you can start a second peer using:
likely observe traffic and behaviors that are not explicitly controlled
by you.
+@node How to connect manually
@subsubsection How to connect manually
If you want to use the @code{peerinfo} tool to connect your peers, you should:
Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG'
@end example
+@node Starting Peers Using the Testbed Service
@subsection Starting Peers Using the Testbed Service
@c \label{sec:testbed}
Then use the DHT API to store and retrieve values in the
network.
-
+@node Developing Applications
@section Developing Applications
+@node gnunet-ext
@subsection gnunet-ext
To develop a new peer-to-peer application or to extend GNUnet we provide
a template build system for writing GNUnet extensions in C. It can be
@item a configuration template for the service (gnunet-ext/src/ext/ext.conf.in)
@end itemize
+@node Adapting the Template
@subsection Adapting the Template
The first step for writing any extension with a new service is to
services name, you have to modify the @code{AC\_OUTPUT} section in @file{configure.ac}
in the @file{gnunet-ext} root.
+@node Writing a Client Application
@section Writing a Client Application
When writing any client application (for example, a command-line
@verbatiminclude tutorial-examples/001.c
@end example
+@node Handling command-line options
@subsection Handling command-line options
Options can then be added easily by adding global variables and
Exercise: Add a few command-line options and print them inside
of @code{run}. What happens if the user gives invalid arguments?
+@node Writing a Client Library
@subsection Writing a Client Library
The first and most important step in writing a client library is to
@file{gnunet\_protocols.h} header (or an extension-specific include
file).
+@node Connecting to the Service
@subsubsection Connecting to the Service
Before a client library can implement the application-specific protocol
The @code{error\_cb} is a function that is to be called whenever
there are errors communicating with the service.
+@node Sending messages
@subsubsection Sending messages
In GNUnet, messages are always sent beginning with a @code{struct GNUNET\_MessageHeader}
unsigned integer (as payload) to a service using some given client
handle.
-
+@node Receiving Replies from the Service
@subsubsection Receiving Replies from the Service
Clients can receive messages from the service using the handlers
Exercise: Figure out where you can pass values to the closures (@code{cls}).
-
+@node Writing a user interface
@subsection Writing a user interface
Given a client library, all it takes to access a service now is to
send a 32-bit integer value based on a number given at the
command-line to the service.
+@node Writing a Service
@section Writing a Service
Before you can test the client you've written so far, you'll need to also
implement the corresponding service.
+@node Code Placement
@subsection Code Placement
New services are placed in their own subdirectory under @file{gnunet/src}.
@file{gnunet-service-SERVICE.h} and several files for tests, including test code
and configuration files.
+@node Starting a Service
@subsection Starting a Service
The key API definition for creating a service is the @code{GNUNET\_SERVICE\_MAIN} macro:
client (for now, by printing a message). What happens if you
forget to call @code{GNUNET\_SERVICE\_client\_continue()}?
-
+@node Interacting directly with other Peers using the CORE Service
@section Interacting directly with other Peers using the CORE Service
FIXME: This section still needs to be updated to the lastest API!
@verbatiminclude tutorial-examples/009.c
@end example
+@node New P2P connections
@subsection New P2P connections
Before any traffic with a different peer can be exchanged, the peer must be
start (and connect) two peers and print a message once your connect
callback is invoked.
+@node Receiving P2P Messages
@subsection Receiving P2P Messages
To receive messages from @code{CORE}, you pass the desired
without message handlers. Which ``connect'' handlers are invoked when
the two peers are connected? Why?
-
+@node Sending P2P Messages
@subsection Sending P2P Messages
You can transmit messages to other peers using the @i{mq} you were
messages lost? How can you transmit messages faster? What happens if
you stop the peer that is receiving your messages?
-
+@node End of P2P connections
@subsection End of P2P connections
If a message handler returns @code{GNUNET\_SYSERR}, the remote peer shuts down or
Exercise: Fix your service to handle peer disconnects.
+@node Storing peer-specific data using the PEERSTORE service
@section Storing peer-specific data using the PEERSTORE service
GNUnet's PEERSTORE service offers a persistorage for arbitrary peer-specific data.
The service handle @code{peerstore_handle} will be needed for all subsequent
PEERSTORE operations.
+@node Storing records
@subsection Storing records
To store a new record, use the following function:
GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
@end example
+@node Retrieving records
@subsection Retrieving records
To retrieve stored records, use the following function:
handle can be used to cancel the iterate operation only before the callback function is called with
a @code{NULL} record.
+@node Monitoring records
@subsection Monitoring records
PEERSTORE offers the functionality of monitoring for new records stored under a specific key
@verbatiminclude tutorial-examples/016.c
@end example
+@node Disconnecting from PEERSTORE
@subsection Disconnecting from PEERSTORE
When the connection to the PEERSTORE service is no longer needed, disconnect using the following
disconnection until all store requests are received by the PEERSTORE service. Otherwise,
it will disconnect immediately.
-
+@node Using the DHT
@section Using the DHT
The DHT allows to store data so other peers in the P2P network can
It is not a hard limit, but a good approximation will make the DHT more
efficient.
+@node Storing data in the DHT
@subsection Storing data in the DHT
Since the DHT is a dynamic environment (peers join and leave frequently)
the data that we put in the DHT does not stay there indefinitely. It is
over time. You might consider using the function @code{GNUNET\_SCHEDULER\_add\_delayed}
and call @code{GNUNET\_DHT\_put} from inside a helper function.
-
+@node Obtaining data from the DHT
@subsection Obtaining data from the DHT
As we saw in the previous example, the DHT works in an asynchronous mode.
Each request to the DHT is executed ``in the background'' and the API
the peers the requests have gone through. In order to convert a peer ID to a string, use
the function @code{GNUNET\_i2s}. Pay attention to the route option parameters in both calls!
+@node Implementing a block plugin
@subsection Implementing a block plugin
In order to store data in the DHT, it is necessary to provide a block
mandatory functions that need to be implemented for a block plugin are
described in the following sections.
+@node Validating requests and replies
@subsubsection Validating requests and replies
The evaluate function should validate a reply or a request. It returns
@file{libgnunetblockgroup.so}. Failure to do so may cause replies to
circle in the network.
+@node Deriving a key from a reply
@subsubsection Deriving a key from a reply
The DHT can operate more efficiently if it is possible to derive a key
@verbatiminclude tutorial-examples/022.c
@end example
+@node Initialization of the plugin
@subsubsection Initialization of the plugin
The plugin is realized as a shared C library. The library must export
@verbatiminclude tutorial-examples/023.c
@end example
+@node Shutdown of the plugin
@subsubsection Shutdown of the plugin
Following GNUnet's general plugin API concept, the plugin must
@verbatiminclude tutorial-examples/024.c
@end example
+@node Integration of the plugin with the build system
@subsubsection Integration of the plugin with the build system
In order to compile the plugin, the @file{Makefile.am} file for the
and all replies but prints information about queries and replies
when the respective validation hooks are called.
+@node Monitoring the DHT
@subsection Monitoring the DHT
It is possible to monitor the functioning of the local DHT service. When monitoring
the DHT, the service will alert the monitoring program of any events,
@verbatiminclude tutorial-examples/026.c
@end example
+@node Debugging with gnunet-arm
@section Debugging with gnunet-arm
Even if services are managed by @command{gnunet-arm}, you can start them with
projects / oweals / gnunet.git / commitdiff