[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [gnunet] 03/05: doc: gnunet-c-tutorial: Add nodes.
From: |
gnunet |
Subject: |
[GNUnet-SVN] [gnunet] 03/05: doc: gnunet-c-tutorial: Add nodes. |
Date: |
Wed, 06 Sep 2017 12:07:06 +0200 |
This is an automated email from the git hooks/post-receive script.
ng0 pushed a commit to branch master
in repository gnunet.
commit 6a2067a3a386856869c60cbf32463947f9f87c5e
Author: ng0 <address@hidden>
AuthorDate: Wed Sep 6 09:43:52 2017 +0000
doc: gnunet-c-tutorial: Add nodes.
---
doc/gnunet-c-tutorial.texi | 63 +++++++++++++++++++++++++++++++++++++---------
1 file changed, 51 insertions(+), 12 deletions(-)
diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi
index 824834c92..156b6a14e 100644
--- a/doc/gnunet-c-tutorial.texi
+++ b/doc/gnunet-c-tutorial.texi
@@ -58,7 +58,7 @@ important and do not hesitate to contact the GNUnet team if
you have
any questions or problems! Check here how to contact the GNUnet
team: @uref{https://gnunet.org/contact_information}
-
address@hidden Installing GNUnet
@section Installing GNUnet
First of all you have to install a current version of GNUnet. You can download
a
@@ -70,6 +70,7 @@ latest development version things can be broken,
functionality can be changed or
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.
address@hidden Obtaining a stable version
@subsection Obtaining a stable version
You can download the latest stable version of GNUnet from GNU FTP mirrors:
@@ -95,6 +96,7 @@ $ cd gnunet
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/}.
address@hidden 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.
@@ -107,6 +109,7 @@ For GNUnet bootstrapping support and the http(s) plugin you
should install libgn
For the filesharing service you should install at least one of the datastore
backends mysql,
sqlite or postgresql.
address@hidden 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
@@ -122,6 +125,7 @@ $ ./bootstrap
The remainder of this tutorial assumes that you have Git branch ``master''
checked out.
address@hidden Compiling and Installing GNUnet
@subsection Compiling and Installing GNUnet
First, you need to install at least libgnupgerror version 1.27
@@ -146,6 +150,7 @@ $ sudo make install
$ cd ..
@end example
address@hidden 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
@@ -173,6 +178,7 @@ $ mkdir ~/.config/
$ touch ~/.config/gnunet.conf
@end example
address@hidden Common Issues - Check your GNUnet installation
@subsection Common Issues - Check your GNUnet installation
You should check your installation to ensure that installing GNUnet
@@ -204,6 +210,7 @@ PASS: test_gnunet_prefix
=============
@end example
address@hidden Background: GNUnet Architecture
@section Background: GNUnet Architecture
GNUnet is organized in layers and services. Each service is composed of a
@@ -247,9 +254,10 @@ client do not affect the service process or other clients.
The service and the
clients communicate via a message protocol to be defined and implemented by
the programmer.
-
address@hidden First Steps with GNUnet
@section First Steps with GNUnet
address@hidden Configure your peer
@subsection Configure your peer
First of all we need to configure your peer. Each peer is started with a
configuration
@@ -280,6 +288,7 @@ GNUNET_HOME = ~/gnunet1/ # Use this directory to store
GNUnet data
SERVERS = # prevent bootstrapping
@end example
address@hidden 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
@@ -304,7 +313,7 @@ You should see an output containing the peer ID similar to:
I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
@end example
-
address@hidden 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
@@ -328,7 +337,7 @@ $ gnunet-statistics -c ~/peer1.conf # print
statistics about current GNUnet sta
$ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT
service
@end example
-
address@hidden 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.
@@ -336,6 +345,7 @@ The process is rather painful, but the description is
somewhat instructive.
In practice, you might prefer the automated method
(@pxref{Starting Peers Using the Testbed Service}).
address@hidden 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
@@ -375,6 +385,7 @@ as needed. Also, make sure the output is different from the
gnunet-peerinfo output for the first peer (otherwise you made an
error in the configuration).
address@hidden 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:
@@ -413,6 +424,7 @@ tricky as you're going to be connected to many more peers
and would
likely observe traffic and behaviors that are not explicitly controlled
by you.
address@hidden How to connect manually
@subsubsection How to connect manually
If you want to use the @code{peerinfo} tool to connect your peers, you should:
@@ -430,6 +442,7 @@ $ gnunet-core -c peer1.conf
Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG'
@end example
address@hidden Starting Peers Using the Testbed Service
@subsection Starting Peers Using the Testbed Service
@c \label{sec:testbed}
@@ -518,9 +531,10 @@ options in the configuration file. See
@uref{https://gnunet.org/supported-topolo
Then use the DHT API to store and retrieve values in the
network.
-
address@hidden Developing Applications
@section Developing Applications
address@hidden 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
@@ -560,6 +574,7 @@ In addition the ext systems provides:
@item a configuration template for the service (gnunet-ext/src/ext/ext.conf.in)
@end itemize
address@hidden Adapting the Template
@subsection Adapting the Template
The first step for writing any extension with a new service is to
@@ -571,6 +586,7 @@ If you want to adapt the template rename the
@file{ext.conf.in} to match your
services name, you have to modify the @code{AC\_OUTPUT} section in
@file{configure.ac}
in the @file{gnunet-ext} root.
address@hidden Writing a Client Application
@section Writing a Client Application
When writing any client application (for example, a command-line
@@ -583,6 +599,7 @@ used, which is typically not needed):
@verbatiminclude tutorial-examples/001.c
@end example
address@hidden Handling command-line options
@subsection Handling command-line options
Options can then be added easily by adding global variables and
@@ -612,6 +629,7 @@ more persistent P2P functions.
Exercise: Add a few command-line options and print them inside
of @code{run}. What happens if the user gives invalid arguments?
address@hidden Writing a Client Library
@subsection Writing a Client Library
The first and most important step in writing a client library is to
@@ -633,6 +651,7 @@ Unique message types must be defined for each message
struct in the
@file{gnunet\_protocols.h} header (or an extension-specific include
file).
address@hidden Connecting to the Service
@subsubsection Connecting to the Service
Before a client library can implement the application-specific protocol
@@ -650,6 +669,7 @@ receive from the service, and which functions handle them.
The @code{error\_cb} is a function that is to be called whenever
there are errors communicating with the service.
address@hidden Sending messages
@subsubsection Sending messages
In GNUnet, messages are always sent beginning with a @code{struct
GNUNET\_MessageHeader}
@@ -678,7 +698,7 @@ Exercise: Define a helper function to transmit a 32-bit
unsigned integer (as payload) to a service using some given client
handle.
-
address@hidden Receiving Replies from the Service
@subsubsection Receiving Replies from the Service
Clients can receive messages from the service using the handlers
@@ -702,7 +722,7 @@ should call a callback provided to your helper function's
API.
Exercise: Figure out where you can pass values to the closures (@code{cls}).
-
address@hidden Writing a user interface
@subsection Writing a user interface
Given a client library, all it takes to access a service now is to
@@ -714,11 +734,13 @@ client application to send a request to the service. For
example,
send a 32-bit integer value based on a number given at the
command-line to the service.
address@hidden 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.
address@hidden Code Placement
@subsection Code Placement
New services are placed in their own subdirectory under @file{gnunet/src}.
@@ -728,6 +750,7 @@ the description of the client-service protocol
@file{SERVICE.h} and P2P protocol
@file{gnunet-service-SERVICE.h} and several files for tests, including test
code
and configuration files.
address@hidden Starting a Service
@subsection Starting a Service
The key API definition for creating a service is the
@code{GNUNET\_SERVICE\_MAIN} macro:
@@ -767,7 +790,7 @@ Exercise: Change the service to ``handle'' the message from
your
client (for now, by printing a message). What happens if you
forget to call @code{GNUNET\_SERVICE\_client\_continue()}?
-
address@hidden 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!
@@ -781,6 +804,7 @@ is connect to the @code{CORE} service using:
@verbatiminclude tutorial-examples/009.c
@end example
address@hidden New P2P connections
@subsection New P2P connections
Before any traffic with a different peer can be exchanged, the peer must be
@@ -798,6 +822,7 @@ Exercise: Create a service that connects to the
@code{CORE}. Then
start (and connect) two peers and print a message once your connect
callback is invoked.
address@hidden Receiving P2P Messages
@subsection Receiving P2P Messages
To receive messages from @code{CORE}, you pass the desired
@@ -814,7 +839,7 @@ handler and start a second peer that only has your ``old''
service
without message handlers. Which ``connect'' handlers are invoked when
the two peers are connected? Why?
-
address@hidden Sending P2P Messages
@subsection Sending P2P Messages
You can transmit messages to other peers using the @i{mq} you were
@@ -832,7 +857,7 @@ transmission? Count using the STATISTICS service on both
ends. Are
messages lost? How can you transmit messages faster? What happens if
you stop the peer that is receiving your messages?
-
address@hidden End of P2P connections
@subsection End of P2P connections
If a message handler returns @code{GNUNET\_SYSERR}, the remote peer shuts down
or
@@ -846,6 +871,7 @@ The disconnect callback looks like the following:
Exercise: Fix your service to handle peer disconnects.
address@hidden 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.
@@ -868,6 +894,7 @@ The first step is to start a connection to the PEERSTORE
service:
The service handle @code{peerstore_handle} will be needed for all subsequent
PEERSTORE operations.
address@hidden Storing records
@subsection Storing records
To store a new record, use the following function:
@@ -891,6 +918,7 @@ void
GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
@end example
address@hidden Retrieving records
@subsection Retrieving records
To retrieve stored records, use the following function:
@@ -914,6 +942,7 @@ The @code{GNUNET_PEERSTORE_iterate} function returns a
handle to the iterate ope
handle can be used to cancel the iterate operation only before the callback
function is called with
a @code{NULL} record.
address@hidden Monitoring records
@subsection Monitoring records
PEERSTORE offers the functionality of monitoring for new records stored under
a specific key
@@ -929,6 +958,7 @@ is broken or the watch operation is canceled:
@verbatiminclude tutorial-examples/016.c
@end example
address@hidden Disconnecting from PEERSTORE
@subsection Disconnecting from PEERSTORE
When the connection to the PEERSTORE service is no longer needed, disconnect
using the following
@@ -941,7 +971,7 @@ If the @code{sync_first} flag is set to @code{GNUNET_YES},
the API will delay th
disconnection until all store requests are received by the PEERSTORE service.
Otherwise,
it will disconnect immediately.
-
address@hidden Using the DHT
@section Using the DHT
The DHT allows to store data so other peers in the P2P network can
@@ -956,6 +986,7 @@ The second parameter indicates how many requests in
parallel to expect.
It is not a hard limit, but a good approximation will make the DHT more
efficient.
address@hidden 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
@@ -978,7 +1009,7 @@ Exercise: Store a value in the DHT periodically to make
sure it is available
over time. You might consider using the function
@code{GNUNET\_SCHEDULER\_add\_delayed}
and call @code{GNUNET\_DHT\_put} from inside a helper function.
-
address@hidden 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
@@ -1000,6 +1031,7 @@ Exercise: Store a value in the DHT and after a while
retrieve it. Show the IDs o
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!
address@hidden Implementing a block plugin
@subsection Implementing a block plugin
In order to store data in the DHT, it is necessary to provide a block
@@ -1011,6 +1043,7 @@ in the service's respective directory. The
mandatory functions that need to be implemented for a block plugin are
described in the following sections.
address@hidden Validating requests and replies
@subsubsection Validating requests and replies
The evaluate function should validate a reply or a request. It returns
@@ -1033,6 +1066,7 @@ typically done using the Bloom filter block group
provided by
@file{libgnunetblockgroup.so}. Failure to do so may cause replies to
circle in the network.
address@hidden 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
@@ -1045,6 +1079,7 @@ just fine with such blocks).
@verbatiminclude tutorial-examples/022.c
@end example
address@hidden Initialization of the plugin
@subsubsection Initialization of the plugin
The plugin is realized as a shared C library. The library must export
@@ -1056,6 +1091,7 @@ validation and obtaining keys (the ones just defined
above).
@verbatiminclude tutorial-examples/023.c
@end example
address@hidden Shutdown of the plugin
@subsubsection Shutdown of the plugin
Following GNUnet's general plugin API concept, the plugin must
@@ -1065,6 +1101,7 @@ little.
@verbatiminclude tutorial-examples/024.c
@end example
address@hidden 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
@@ -1079,6 +1116,7 @@ Exercise: Write a block plugin that accepts all queries
and all replies but prints information about queries and replies
when the respective validation hooks are called.
address@hidden 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,
@@ -1094,6 +1132,7 @@ is called with all the information about the event.
@verbatiminclude tutorial-examples/026.c
@end example
address@hidden Debugging with gnunet-arm
@section Debugging with gnunet-arm
Even if services are managed by @command{gnunet-arm}, you can start them with
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [gnunet] branch master updated (0e0e6e359 -> 292cc51b3), gnunet, 2017/09/06
- [GNUnet-SVN] [gnunet] 01/05: doc: Makefile: Add gnunet-c-tutorial., gnunet, 2017/09/06
- [GNUnet-SVN] [gnunet] 04/05: doc: gnunet-c-tutorial: fix warnings., gnunet, 2017/09/06
- [GNUnet-SVN] [gnunet] 05/05: doc: gnunet-c-tutorial: add @chapter's., gnunet, 2017/09/06
- [GNUnet-SVN] [gnunet] 03/05: doc: gnunet-c-tutorial: Add nodes.,
gnunet <=
- [GNUnet-SVN] [gnunet] 02/05: doc: gnunet-c-tutorial.texi, chapters/installation.texi: fix compilation warnings., gnunet, 2017/09/06