From 6a2067a3a386856869c60cbf32463947f9f87c5e Mon Sep 17 00:00:00 2001 From: ng0 Date: Wed, 6 Sep 2017 09:43:52 +0000 Subject: [PATCH] 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} - +@node 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. +@node 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/}. +@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. @@ -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. +@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 @@ -122,6 +125,7 @@ $ ./bootstrap 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 @@ -146,6 +150,7 @@ $ sudo make install $ 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 @@ -173,6 +178,7 @@ $ mkdir ~/.config/ $ 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 @@ -204,6 +210,7 @@ PASS: test_gnunet_prefix ============= @end example +@node 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. - +@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 @@ -280,6 +288,7 @@ GNUNET_HOME = ~/gnunet1/ # Use this directory to store GNUnet data 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 @@ -304,7 +313,7 @@ You should see an output containing the peer ID similar to: 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 @@ -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 - +@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. @@ -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}). +@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 @@ -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). +@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: @@ -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. +@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: @@ -430,6 +442,7 @@ $ gnunet-core -c peer1.conf Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG' @end example +@node 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. - +@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 @@ -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 +@node 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. +@node 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 +@node 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? +@node 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). +@node 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. +@node 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. - +@node 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}). - +@node 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. +@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}. @@ -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. +@node 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()}? - +@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! @@ -781,6 +804,7 @@ is connect to the @code{CORE} service using: @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 @@ -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. +@node 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? - +@node 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? - +@node 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. +@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. @@ -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. +@node 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 +@node 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. +@node 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 +@node 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. - +@node 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. +@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 @@ -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. - +@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 @@ -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! +@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 @@ -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. +@node 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. +@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 @@ -1045,6 +1079,7 @@ just fine with such blocks). @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 @@ -1056,6 +1091,7 @@ validation and obtaining keys (the ones just defined above). @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 @@ -1065,6 +1101,7 @@ little. @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 @@ -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. +@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, @@ -1094,6 +1132,7 @@ is called with all the information about the event. @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 -- 2.25.1