1 \documentclass[10pt]{article}
2 \usepackage[ansinew]{inputenc}
3 \usepackage{makeidx,amsmath,amssymb,exscale,multicol,epsfig,graphics,verbatim,ulem}
4 \usepackage{epsfig,geometry,url,listings,subcaption}
5 \usepackage{boxedminipage}
6 \usepackage[T1]{fontenc}%required
8 \geometry{headsep=3ex,hscale=0.9}
11 \hypersetup{pdftitle={GNUnet C Tutorial},
13 pdfauthor={Christian Grothoff <christian@grothoff.org>},
14 pdfkeywords={p2p,search,gnunet,tutorial}
15 %,pdfpagemode={FullScreen}
24 literate={*}{{\char42}}1
28 \newcommand{\exercise}[1]{\noindent\begin{boxedminipage}{\textwidth}{\bf Exercise:} #1 \end{boxedminipage}}
33 language=C, % choose the language of the code
34 basicstyle=\footnotesize, % the size of the fonts that are used for the code
35 numbers=left, % where to put the line-numbers
36 numberstyle=\footnotesize, % the size of the fonts that are used for the line-numbers
37 stepnumber=1, % the step between two line-numbers. If it is 1 each line will be numbered
38 numbersep=5pt, % how far the line-numbers are from the code
39 backgroundcolor=\color{white}, % choose the background color. You must add \usepackage{color}
40 showspaces=false, % show spaces adding particular underscores
41 showstringspaces=false, % underline spaces within strings
42 showtabs=false, % show tabs within strings adding particular underscores
43 frame=single, % adds a frame around the code
44 tabsize=2, % sets default tabsize to 2 spaces
45 captionpos=b, % sets the caption-position to bottom
46 breaklines=true, % sets automatic line breaking
47 breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace
48 escapeinside={\%*}{*)} % if you want to add a comment within your code
53 \large {A Tutorial for GNUnet 0.10.x (C version)}
55 Christian Grothoff $\qquad$ Bart Polot $\qquad$ Matthias Wachs
59 This tutorials explains how to install GNUnet on a GNU/Linux system and gives an introduction on how
60 GNUnet can be used to develop a Peer-to-Peer application. Detailed installation instructions for
61 various operating systems and a detailed list of all dependencies can be found on our website at
62 \url{https://gnunet.org/installation}.
64 \textbf{Please read this tutorial carefully since every single step is
65 important and do not hesitate to contact the GNUnet team if you have
66 any questions or problems! Check here how to contact the GNUnet
67 team: \url{https://gnunet.org/contact_information}}
70 \section{Installing GNUnet}
72 First of all you have to install a current version of GNUnet. You can download a
73 tarball of a stable version from GNU FTP mirrors or obtain the latest development
74 version from our Git repository.
76 Most of the time you should prefer to download the stable version since with the
77 latest development version things can be broken, functionality can be changed or tests
78 can fail. You should only use the development version if you know that you require a
79 certain feature or a certain issue has been fixed since the last release.
81 \subsection{Obtaining a stable version}
83 You can download the latest stable version of GNUnet from GNU FTP mirrors:
85 \url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz}
87 You should also download the signature file and verify the integrity of the tarball.
89 \url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz.sig}
91 To verify the signature you should first import the GPG key used to sign the tarball
92 \lstset{language=bash}
94 $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E
96 And use this key to verify the tarball's signature
97 \lstset{language=bash}
99 $ gpg --verify gnunet-0.10.x.tar.gz.sig gnunet-0.10.x.tar.gz
101 After successfully verifying the integrity you can extract the tarball using
102 \lstset{language=bash}
104 $ tar xvzf gnunet-0.10.x.tar.gz
105 $ mv gnunet-0.10.x gnunet # we will use the directory "gnunet" in the remainder of this document
109 However, please note that stable versions can be very outdated, as a developer
110 you are strongly encouraged to use the version from \url{https://gnunet.org/git/}.
112 \subsection{Installing Build Tool Chain and Dependencies}
114 To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies.
115 Please have a look at \url{https://gnunet.org/dependencies} for a list of required dependencies
116 and \url{https://gnunet.org/generic_installation} for specific instructions for your operating system.
118 Please check the notes at the end of the configure process about required dependencies.
120 For GNUnet bootstrapping support and the http(s) plugin you should install \texttt{libgnurl}.
121 For the filesharing service you should install at least one of the datastore backends \texttt{mysql},
122 \texttt{sqlite} or \texttt{postgresql}.
124 \subsection{Obtaining the latest version from Git}
126 The latest development version can obtained from our Git repository. To obtain
127 the code you need Git installed and checkout the repository using:
128 \lstset{language=bash}
130 $ git clone https://gnunet.org/git/gnunet
132 After cloning the repository you have to execute
133 \lstset{language=bash}
139 The remainder of this tutorial assumes that you have Git Master checked out.
142 \subsection{Compiling and Installing GNUnet}
144 First, you need to install at least {\tt libgnupgerror} version
145 1.27\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.27.tar.bz2}}
146 and {\tt libgcrypt} version
147 1.7.6\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.7.6.tar.bz2}}.
149 \lstset{language=bash}
151 $ wget ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.27.tar.bz2
152 $ tar xf libgpg-error-1.27.tar.bz2
153 $ cd libgpg-error-1.27
159 \lstset{language=bash}
161 $ wget ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.7.6.tar.bz2
162 $ tar xf libgcrypt-1.7.6.tar.bz2
170 Assuming all dependencies are installed, the following commands will
171 compile and install GNUnet in your home directory. You can specify the
172 directory where GNUnet will be installed by changing the
173 \lstinline|--prefix| value when calling \lstinline|./configure|. If
174 you do not specifiy a prefix, GNUnet is installed in the directory
175 \lstinline|/usr/local|. When developing new applications you may want
176 to enable verbose logging by adding
177 \lstinline|--enable-logging=verbose|:
179 \lstset{language=bash}
181 $ ./configure --prefix=$PREFIX --enable-logging
186 After installing GNUnet you have to add your GNUnet installation to your path
187 environmental variable. In addition you have to create the \lstinline|.config|
188 directory in your home directory where GNUnet stores its data and an empty
189 GNUnet configuration file:
191 \lstset{language=bash}
193 $ export PATH=$PATH:$PREFIX/bin
194 $ echo export PATH=$PREFIX/bin:\\$PATH >> ~/.bashrc
196 $ touch ~/.config/gnunet.conf
200 \subsection{Common Issues - Check your GNUnet installation}
202 You should check your installation to ensure that installing GNUnet
203 was successful up to this point. You should be able to access GNUnet's
204 binaries and run GNUnet's self check.
205 \lstset{language=bash}
209 should return \lstinline|$PREFIX/bin/gnunet-arm|. It should be
210 located in your GNUnet installation and the output should not be
211 empty. If you see an output like:
212 \lstset{language=bash}
217 check your {\tt PATH} variable to ensure GNUnet's {\tt bin} directory is included.
219 GNUnet provides tests for all of its subcomponents. Run
220 \lstset{language=bash}
224 to execute tests for all components. {\tt make check} traverses all subdirectories in {\tt src}.
225 For every subdirectory you should get a message like this:
228 make[2]: Entering directory `/home/$USER/gnunet/contrib'
229 PASS: test_gnunet_prefix
236 \section{Background: GNUnet Architecture}
238 GNUnet is organized in layers and services. Each service is composed of a
239 main service implementation and a client library for other programs to use
240 the service's functionality, described by an API. This approach is shown in
241 figure~\ref{fig:service}. Some services provide an additional command line
242 tool to enable the user to interact with the service.
244 Very often it is other GNUnet services that will use these APIs to build the
245 higher layers of GNUnet on top of the lower ones. Each layer expands or extends
246 the functionality of the service below (for instance, to build a mesh on top of
247 a DHT). See figure ~\ref{fig:interaction} for an illustration of this approach.
252 \begin{subfigure}[b]{0.3\textwidth}
254 \includegraphics[width=\textwidth]{figs/Service.pdf}
255 \caption{Service with API and network protocol}
259 \begin{subfigure}[b]{0.3\textwidth}
261 \includegraphics[width=\textwidth]{figs/System.pdf}
262 \caption{Service interaction}
263 \label{fig:interaction}
266 \caption{GNUnet's layered system architecture}
269 The main service implementation runs as a standalone process in the operating
270 system and the client code runs as part of the client program, so crashes of a
271 client do not affect the service process or other clients. The service and the
272 clients communicate via a message protocol to be defined and implemented by
276 \section{First Steps with GNUnet}
278 \subsection{Configure your peer}
280 First of all we need to configure your peer. Each peer is started with a configuration containing settings for GNUnet itself and its services. This configuration is based on the default configuration shipped with GNUnet and can be modified. The default configuration is located in the {\tt \$PREFIX/share/gnunet/config.d} directory. When starting a peer, you can specify a customized configuration using the the {\tt$-c$} command line switch when starting the ARM service and all other services. When using a modified configuration the default values are loaded and only values specified in the configuration file will replace the default values.
282 Since we want to start additional peers later, we need
283 some modifications from the default configuration. We need to create a separate service home and a file containing our modifications for this peer:
284 \lstset{language=bash}
290 Now add the following lines to peer1.conf to use this directory. For
291 simplified usage we want to prevent the peer to connect to the GNUnet
292 network since this could lead to confusing output. This modifications
293 will replace the default settings:
296 GNUNET_HOME = ~/gnunet1/ # Use this directory to store GNUnet data
298 SERVERS = # prevent bootstrapping
302 \subsection{Start a peer}
303 Each GNUnet instance (called peer) has an identity (\textit{peer ID}) based on a
304 cryptographic public private key pair. The peer ID is the printable hash of the
307 GNUnet services are controlled by a master service the so called \textit{Automatic Restart Manager} (ARM).
308 ARM starts, stops and even restarts services automatically or on demand when a client connects.
309 You interact with the ARM service using the \lstinline|gnunet-arm| tool.
310 GNUnet can then be started with \lstinline|gnunet-arm -s| and stopped with
311 \lstinline|gnunet-arm -e|. An additional service not automatically started
312 can be started using \lstinline|gnunet-arm -i <service name>| and stopped
313 using \lstinline|gnunet-arm -k <servicename>|.
315 Once you have started your peer, you can use many other GNUnet commands
316 to interact with it. For example, you can run:
317 \lstset{language=bash}
321 to obtain the public key of your peer.
322 You should see an output containing the peer ID similar to:
323 \lstset{language=bash}
325 I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
329 \subsection{Monitor a peer}
331 In this section, we will monitor the behaviour of our peer's DHT service with respect to a
332 specific key. First we will start GNUnet and then start the DHT service and use the DHT monitor tool
333 to monitor the PUT and GET commands we issue ussing the \lstinline|gnunet-dht-put| and
334 \lstinline|gnunet-dht-get| commands. Using the ``monitor'' line given below, you can observe the behavior of
335 your own peer's DHT with respect to the specified KEY:
337 \lstset{language=bash}
339 $ gnunet-arm -c ~/peer1.conf -s # start gnunet with all default services
340 $ gnunet-arm -c ~/peer1.conf -i dht # start DHT service
341 $ cd ~/gnunet/src/dht;
342 $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY
344 Now open a separate terminal and change again to the \lstinline|gnunet/src/dht| directory:
345 \lstset{language=bash}
347 $ cd ~/gnunet/src/dht
348 $ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE # put VALUE under KEY in the DHT
349 $ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY # get key KEY from the DHT
350 $ gnunet-statistics -c ~/peer1.conf # print statistics about current GNUnet state
351 $ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service
356 \subsection{Starting Two Peers by Hand}
358 This section describes how to start two peers on the same machine by hand.
359 The process is rather painful, but the description is somewhat instructive.
360 In practice, you might prefer the automated method described in
361 Section~\ref{sec:testbed}.
363 \subsubsection{Setup a second peer}
364 We will now start a second peer on your machine.
365 For the second peer, you will need to manually create a modified
366 configuration file to avoid conflicts with ports and directories.
367 A peers configuration file is by default located in {\tt ~/.gnunet/gnunet.conf}.
368 This file is typically very short or even empty as only the differences to the
369 defaults need to be specified. The defaults are located in
370 many files in the {\tt \$PREFIX/share/gnunet/config.d} directory.
372 To configure the second peer, use the files {\tt
373 \$PREFIX/share/gnunet/config.d} as a template for your main
376 \lstset{language=bash}
377 \lstset{language=bash}
379 $ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf
381 Now you have to edit {\tt peer2.conf} and change:
384 \item{\texttt{GNUNET\_TEST\_HOME} under \texttt{PATHS}}
385 \item{Every (uncommented) value for ``\texttt{PORT}'' (add 10000) in any
386 section (the option may be commented out if \texttt{PORT} is
387 prefixed by "\#", in this case, UNIX domain sockets are used
388 and the PORT option does not need to be touched) }
389 \item{Every value for ``\texttt{UNIXPATH}'' in any section (e.g. by adding a "-p2" suffix)}
391 to a fresh, unique value. Make sure that the \texttt{PORT} numbers stay
392 below 65536. From now on, whenever you interact with the second
393 peer, you need to specify {\tt -c peer2.conf} as an additional
394 command line argument.
396 Now, generate the 2nd peer's private key:
398 \lstset{language=bash}
400 $ gnunet-peerinfo -s -c peer2.conf
404 This may take a while, generate entropy using your keyboard or mouse
405 as needed. Also, make sure the output is different from the {\tt
406 gnunet-peerinfo} output for the first peer (otherwise you made an
407 error in the configuration).
409 \subsubsection{Start the second peer and connect the peers}
411 Then, you can start a second peer using:
412 \lstset{language=bash}
414 $ gnunet-arm -c peer2.conf -s
415 $ gnunet-arm -c peer2.conf -i dht
416 $ ~/gnunet/src/dht/gnunet-dht-put -c peer2.conf -k KEY -d VALUE
417 $ ~/gnunet/src/dht/gnunet-dht-get -c peer2.conf -k KEY
419 If you want the two peers to connect, you have multiple options:
422 \item UDP neighbour discovery (automatic)
423 \item Setup a bootstrap server
424 \item Connect manually
426 To setup peer 1 as bootstrapping server change the configuration of
427 the first one to be a hostlist server by adding the following lines to
428 \texttt{peer1.conf} to enable bootstrapping server:
434 Then change {\tt peer2.conf} and replace the ``\texttt{SERVERS}'' line in the ``\texttt{[hostlist]}'' section with
435 ``\texttt{http://localhost:8080/}''. Restart both peers using:
437 $ gnunet-arm -c peer1.conf -e # stop first peer
438 $ gnunet-arm -c peer1.conf -s # start first peer
439 $ gnunet-arm -c peer2.conf -s # start second peer
442 Note that if you start your peers without changing these settings, they
443 will use the ``global'' hostlist servers of the GNUnet P2P network and
444 likely connect to those peers. At that point, debugging might become
445 tricky as you're going to be connected to many more peers and would
446 likely observe traffic and behaviors that are not explicitly controlled
449 \subsubsection{How to connect manually}
451 If you want to use the \texttt{peerinfo} tool to connect your peers, you should:
454 \item{Set {\tt FORCESTART = NO} in section {\tt hostlist} (to not connect to the global GNUnet)}
455 \item{Start both peers running {\tt gnunet-arm -c peer1.conf -s} and {\tt gnunet-arm -c peer2.conf -s}}
456 \item{Get \texttt{HELLO} message of the first peer running {\tt gnunet-peerinfo -c peer1.conf -g}}
457 \item{Give the output to the second peer by running {\tt gnunet-peerinfo -c peer2.conf -p '<output>'}}
460 Check that they are connected using {\tt gnunet-core -c peer1.conf}, which should give you the other peer's
462 \lstset{language=bash}
464 $ gnunet-core -c peer1.conf
465 Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG'
468 \subsection{Starting Peers Using the Testbed Service} \label{sec:testbed}
470 GNUnet's testbed service is used for testing scenarios where a number of peers
471 are to be started. The testbed can manage peers on a single host or on multiple
472 hosts in a distributed fashion. On a single affordable computer, it should be
473 possible to run around tens of peers without drastically increasing the load on the
476 The testbed service can be access through its API
477 \texttt{include/gnunet\_testbed\_service.h}. The API provides many routines for
478 managing a group of peers. It also provides a helper function
479 \texttt{GNUNET\_TESTBED\_test\_run()} to quickly setup a minimalistic testing
480 environment on a single host.
482 This function takes a configuration file which will be used as a template
483 configuration for the peers. The testbed takes care of modifying relevant
484 options in the peers' configuration such as SERVICEHOME, PORT, UNIXPATH to
485 unique values so that peers run without running into conflicts. It also checks
486 and assigns the ports in configurations only if they are free.
488 Additionally, the testbed service also reads its options from the same
489 configuration file. Various available options and details about them can be
490 found in the testbed default configuration file \texttt{src/testbed/testbed.conf}.
492 With the testbed API, a sample test case can be structured as follows:
493 % <lynX> Is there a way to pick a more readable font for this include?
495 \lstinputlisting{testbed_test.c}
496 The source code for the above listing can be found at
497 \url{https://gnunet.org/git/gnunet.git/tree/doc/testbed_test.c}
498 or in the {\tt doc/} folder of your repository check-out.
499 After installing GNUnet, the above source code can be compiled as:
500 \lstset{language=bash}
502 $ export CPPFLAGS="-I/path/to/gnunet/headers"
503 $ export LDFLAGS="-L/path/to/gnunet/libraries"
504 $ gcc $CPPFLAGS $LDFLAGS -o testbed-test testbed_test.c -lgnunettestbed -lgnunetdht -lgnunetutil
505 $ touch template.conf # Generate (empty) configuration
506 $ ./testbed-test # run it (press CTRL-C to stop)
508 The \texttt{CPPFLAGS} and \texttt{LDFLAGS} are necessary if GNUnet is installed
509 into a different directory other than \texttt{/usr/local}.
511 All of testbed API's peer management functions treat management actions as
512 operations and return operation handles. It is expected that the operations
513 begin immediately, but they may get delayed (to balance out load on the system).
514 The program using the API then has to take care of marking the operation as
515 ``done'' so that its associated resources can be freed immediately and other
516 waiting operations can be executed. Operations will be canceled if they are
517 marked as ``done'' before their completion.
519 An operation is treated as completed when it succeeds or fails. Completion of
520 an operation is either conveyed as events through \textit{controller event
521 callback} or through respective operation completion callbacks. In functions
522 which support completion notification through both controller event callback and
523 operation completion callback, first the controller event callback will be
524 called. If the operation is not marked as done in that callback or if the
525 callback is given as NULL when creating the operation, the operation completion
526 callback will be called. The API documentation shows which event are to be
527 expected in the controller event notifications. It also documents any
528 exceptional behaviour.
530 Once the peers are started, test cases often need to connect some of the peers'
531 services. Normally, opening a connect to a peer's service requires the peer's
532 configuration. While using testbed, the testbed automatically generates
533 per-peer configuration. Accessing those configurations directly through file
534 system is discouraged as their locations are dynamically created and will be
535 different among various runs of testbed. To make access to these configurations
536 easy, testbed API provides the function
537 \texttt{GNUNET\_TESTBED\_service\_connect()}. This function fetches the
538 configuration of a given peer and calls the \textit{Connect Adapter}.
539 In the example code, it is the \texttt{dht\_ca}. A connect adapter is expected
540 to open the connection to the needed service by using the provided configuration
541 and return the created service connection handle. Successful connection to the
542 needed service is signaled through \texttt{service\_connect\_comp\_cb}.
544 A dual to connect adapter is the \textit{Disconnect Adapter}. This callback is
545 called after the connect adapter has been called when the operation from
546 \texttt{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''. It has to
547 disconnect from the service with the provided service handle (\texttt{op\_result}).
549 \exercise{Find out how many peers you can run on your system.}
551 \exercise{Find out how to create a 2D torus topology by changing the
552 options in the configuration file.\footnote{See \url{https://gnunet.org/content/supported-topologies}}
553 Then use the DHT API to store and retrieve values in the
557 \section{Developing Applications}
559 \subsection{gnunet-ext}
560 To develop a new peer-to-peer application or to extend GNUnet we provide
561 a template build system for writing GNUnet extensions in C. It can be
564 \lstset{language=bash}
566 $ git clone https://gnunet.org/git/gnunet-ext
569 $ ./configure --prefix=$PREFIX --with-gnunet=$PREFIX
576 The GNUnet ext template includes examples and a working buildsystem for a new GNUnet service.
577 A common GNUnet service consists of the following parts which will be discussed in detail in the
578 remainder of this document. The functionality of a GNUnet service is implemented in:
582 \item the GNUnet service (\lstinline|gnunet-ext/src/ext/gnunet-service-ext.c|)
583 \item the client API (\lstinline|gnunet-ext/src/ext/ext_api.c|)
584 \item the client application using the service API (\lstinline|gnunet-ext/src/ext/gnunet-ext.c|)
589 The interfaces for these entities are defined in:
592 \item client API interface (\lstinline|gnunet-ext/src/ext/ext.h|)
593 \item the service interface (\lstinline|gnunet-ext/src/include/gnunet_service_SERVICE.h|)
594 \item the P2P protocol (\lstinline|gnunet-ext/src/include/gnunet_protocols_ext.h|)
598 In addition the \texttt{ext} systems provides:
601 \item a test testing the API (\lstinline|gnunet-ext/src/ext/test_ext_api.c|)
602 \item a configuration template for the service (\lstinline|gnunet-ext/src/ext/ext.conf.in|)
606 \subsection{Adapting the Template}
608 The first step for writing any extension with a new service is to
609 ensure that the {\tt ext.conf.in} file contains entries for the
610 \texttt{UNIXPATH}, \texttt{PORT} and \texttt{BINARY} for the service in a section named after
613 If you want to adapt the template rename the {\tt ext.conf.in} to match your
614 services name, you have to modify the \texttt{AC\_OUTPUT} section in {\tt configure.ac}
615 in the \texttt{gnunet-ext} root.
617 \section{Writing a Client Application}
619 When writing any client application (for example, a command-line
620 tool), the basic structure is to start with the {\tt
621 GNUNET\_PROGRAM\_run} function. This function will parse
622 command-line options, setup the scheduler and then invoke the {\tt
623 run} function (with the remaining non-option arguments) and a handle
624 to the parsed configuration (and the configuration file name that was
625 used, which is typically not needed):
629 #include <gnunet/platform.h>
630 #include <gnunet/gnunet_util_lib.h>
638 const struct GNUNET_CONFIGURATION_Handle *cfg)
645 main (int argc, char *const *argv)
647 static const struct GNUNET_GETOPT_CommandLineOption options[] = {
648 GNUNET_GETOPT_OPTION_END
651 GNUNET_PROGRAM_run (argc,
654 gettext_noop ("binary description text"),
655 options, &run, NULL)) ? ret : 1;
659 \subsection{Handling command-line options}
661 Options can then be added easily by adding global variables and
662 expanding the {\tt options} array. For example, the following would
663 add a string-option and a binary flag (defaulting to {\tt NULL} and
664 {\tt GNUNET\_NO} respectively):
668 static char *string_option;
672 static const struct GNUNET_GETOPT_CommandLineOption options[] = {
673 {'s', "name", "SOMESTRING",
674 gettext_noop ("text describing the string_option NAME"), 1,
675 &GNUNET_GETOPT_set_string, &string_option},
677 gettext_noop ("text describing the flag option"), 0,
678 &GNUNET_GETOPT_set_one, &a_flag},
679 GNUNET_GETOPT_OPTION_END
681 string_option = NULL;
682 a_flag = GNUNET_SYSERR;
686 Issues such as displaying some helpful text describing options using
687 the {\tt --help} argument and error handling are taken care of when
688 using this approach. Other {\tt GNUNET\_GETOPT\_}-functions can be used
689 to obtain integer value options, increment counters, etc. You can
690 even write custom option parsers for special circumstances not covered
691 by the available handlers. To check if an argument was specified by the
692 user you initialize the variable with a specific value (e.g. NULL for
693 a string and GNUNET\_SYSERR for a integer) and check after parsing
694 happened if the values were modified.
696 Inside the {\tt run} method, the program would perform the
697 application-specific logic, which typically involves initializing and
698 using some client library to interact with the service. The client
699 library is supposed to implement the IPC whereas the service provides
700 more persistent P2P functions.
702 \exercise{Add a few command-line options and print them inside
703 of {\tt run}. What happens if the user gives invalid arguments?}
705 \subsection{Writing a Client Library}
707 The first and most important step in writing a client library is to
708 decide on an API for the library. Typical API calls include
709 connecting to the service, performing application-specific requests
710 and cleaning up. Many examples for such service APIs can be found
711 in the {\tt gnunet/src/include/gnunet\_*\_service.h} files.
713 Then, a client-service protocol needs to be designed. This typically
714 involves defining various message formats in a header that will be
715 included by both the service and the client library (but is otherwise
716 not shared and hence located within the service's directory and not
717 installed by {\tt make install}). Each message must start with a {\tt
718 struct GNUNET\_MessageHeader} and must be shorter than 64k. By
719 convention, all fields in IPC (and P2P) messages must be in big-endian
720 format (and thus should be read using {\tt ntohl} and similar
721 functions and written using {\tt htonl} and similar functions).
722 Unique message types must be defined for each message struct in the
723 {\tt gnunet\_protocols.h} header (or an extension-specific include
726 \subsubsection{Connecting to the Service}
728 Before a client library can implement the application-specific protocol
729 with the service, a connection must be created:
733 struct GNUNET_MQ_MessageHandlers handlers[] = {
735 GNUNET_MQ_handler_end ()
737 struct GNUNET_MQ_Handle *mq;
739 mq = GNUNET_CLIENT_connect (cfg, "service-name", handlers, &error_cb, NULL);
742 As a result a {\tt GNUNET\_MQ\_Handle} is returned
743 which can to used henceforth to transmit messages to
745 The complete MQ API can be found in {\tt gnunet\_mq\_lib.h}.
746 The {\tt hanlders} array in the example above is incomplete.
747 Here is where you will define which messages you expect to
748 receive from the service, and which functions handle them.
749 The {\tt error\_cb} is a function that is to be called whenever
750 there are errors communicating with the service.
752 \subsubsection{Sending messages}
754 In GNUnet, messages are always sent beginning with a {\tt struct GNUNET\_MessageHeader}
755 in big endian format. This header defines the size and the type of the
756 message, the payload follows after this header.
760 struct GNUNET_MessageHeader
762 uint16_t size GNUNET_PACKED;
763 uint16_t type GNUNET_PACKED;
767 Existing message types are defined in {\tt gnunet\_protocols.h}\\
768 A common way to create a message is with an envelope:
772 struct GNUNET_MQ_Envelope *env;
773 struct GNUNET_MessageHeader *msg;
775 env = GNUNET_MQ_msg_extra (msg, payload_size, GNUNET_MY_MESSAGE_TYPE);
776 memcpy (&msg[1], &payload, payload_size);
777 // Send message via message queue 'mq'
778 GNUNET_mq_send (mq, env);
781 \exercise{Define a message struct that includes a 32-bit
782 unsigned integer in addition to the standard GNUnet MessageHeader.
783 Add a C struct and define a fresh protocol number for your message.
784 (Protocol numbers in gnunet-ext are defined in \lstinline|gnunet-ext/src/include/gnunet_protocols_ext.h|)}
786 \exercise{Find out how you can determine the number of messages in a message queue.}
788 \exercise{Find out how you can determine when a message you have queued was actually transmitted.}
790 \exercise{Define a helper function to transmit a 32-bit
791 unsigned integer (as payload) to a service using some given client
795 \subsubsection{Receiving Replies from the Service}
797 Clients can receive messages from the service using the handlers
798 specified in the {\tt handlers} array we specified when connecting
799 to the service. Entries in the the array are usually created using
800 one of two macros, depending on whether the message is fixed size
801 or variable size. Variable size messages are managed using two
802 callbacks, one to check that the message is well-formed, the other
803 to actually process the message. Fixed size messages are fully
804 checked by the MQ-logic, and thus only need to provide the handler
805 to process the message. Note that the prefixes {\tt check\_}
806 and {\tt handle\_} are mandatory.
811 handle_fix (void *cls, const struct MyMessage *msg)
817 check_var (void *cls, const struct MyVarMessage *msg)
819 // check 'msg' is well-formed
824 handle_var (void *cls, const struct MyVarMessage *msg)
829 struct GNUNET_MQ_MessageHandler handlers[] = {
830 GNUNET_MQ_hd_fixed_size (fix,
831 GNUNET_MESSAGE_TYPE_MY_FIX,
834 GNUNET_MQ_hd_fixed_size (var,
835 GNUNET_MESSAGE_TYPE_MY_VAR,
839 GNUNET_MQ_handler_end ()
843 \exercise{Expand your helper function to receive a response message
844 (for example, containing just the {\tt struct GNUnet MessageHeader}
845 without any payload). Upon receiving the service's response, you
846 should call a callback provided to your helper function's API.}
848 \exercise{Figure out where you can pass values to the closures ({\tt cls}).}
851 \subsection{Writing a user interface}
853 Given a client library, all it takes to access a service now is to
854 combine calls to the client library with parsing command-line
857 \exercise{Call your client API from your {\tt run()} method in your
858 client application to send a request to the service. For example,
859 send a 32-bit integer value based on a number given at the
860 command-line to the service.}
864 \section{Writing a Service}
866 Before you can test the client you've written so far, you'll need to also
867 implement the corresponding service.
870 \subsection{Code Placement}
872 New services are placed in their own subdirectory under {\tt gnunet/src}.
873 This subdirectory should contain the API implementation file {\tt SERVICE\_api.c},
874 the description of the client-service protocol {\tt SERVICE.h} and P2P protocol
875 {\tt SERVICE\_protocol.h}, the implementation of the service itself
876 {\tt gnunet-service-SERVICE.h} and several files for tests, including test code
877 and configuration files.
879 \subsection{Starting a Service}
881 The key API definition for creating a service is the {\tt GNUNET\_SERVICE\_MAIN} macro:
886 GNUNET_SERVICE_OPTION_NONE,
889 &client_disconnect_cb,
891 GNUNET_MQ_hd_fixed_size (...),
892 GNUNET_MQ_hd_var_size (...),
893 GNUNET_MQ_handler_end ());
896 In addition to the service name and flags, the macro takes three
897 functions, typically called {\tt run}, {\tt client\_connect\_cb} and
898 {\tt client\_disconnect\_cb} as well as an array of message handlers
899 that will be called for incoming messages from clients.
901 A minimal version of the three central service funtions would look
908 const struct GNUNET_CONFIGURATION_Handle *c,
909 struct GNUNET_SERVICE_Handle *service)
914 client_connect_cb (void *cls,
915 struct GNUNET_SERVICE_Client *c,
916 struct GNUNET_MQ_Handle *mq)
922 client_disconnect_cb (void *cls,
923 struct GNUNET_SERVICE_Client *c,
926 GNUNET_assert (c == internal_cls);
930 \exercise{Write a stub service that processes no messages at all
931 in your code. Create a default configuration for it, integrate it
932 with the build system and start the service from {\tt
933 gnunet-service-arm} using {\tt gnunet-arm -i NAME}.}
935 \exercise{Figure out how to set the closure ({\tt cls}) for handlers
938 \exercise{Figure out how to send messages from the service back to the
941 Each handler function in the service {\bf must} eventually (possibly in some
942 asynchronous continuation) call {\tt GNUNET\_SERVICE\_client\_continue()}.
943 Only after this call additional messages from the same client may
944 be processed. This way, the service can throttle processing messages
945 from the same client.
947 \exercise{Change the service to ``handle'' the message from your
948 client (for now, by printing a message). What happens if you
949 forget to call {\tt GNUNET\_SERVICE\_client\_continue()}?}
952 \section{Interacting directly with other Peers using the CORE Service}
954 FIXME: This section still needs to be updated to the lastest API!
956 One of the most important services in GNUnet is the \texttt{CORE} service
957 managing connections between peers and handling encryption between peers.
959 One of the first things any service that extends the P2P protocol typically does
960 is connect to the \texttt{CORE} service using:
964 #include <gnunet/gnunet_core_service.h>
966 struct GNUNET_CORE_Handle *
967 GNUNET_CORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
969 GNUNET_CORE_StartupCallback init,
970 GNUNET_CORE_ConnectEventHandler connects,
971 GNUNET_CORE_DisconnectEventHandler disconnects,
972 const struct GNUNET_MQ_MessageHandler *handlers);
975 \subsection{New P2P connections}
977 Before any traffic with a different peer can be exchanged, the peer must be
978 known to the service. This is notified by the \texttt{CORE} {\tt connects} callback,
979 which communicates the identity of the new peer to the service:
985 const struct GNUNET_PeerIdentity *peer,
986 struct GNUNET_MQ_Handle *mq)
992 Note that whatever you return from {\tt connects} is given as the
993 {\it cls} argument to the message handlers for messages from
996 \exercise{Create a service that connects to the \texttt{CORE}. Then
997 start (and connect) two peers and print a message once your connect
998 callback is invoked.}
1000 \subsection{Receiving P2P Messages}
1002 To receive messages from \texttt{CORE}, you pass the desired
1003 {\em handlers} to the {\tt GNUNET\_CORE\_connect()} function,
1004 just as we showed for services.
1006 It is your responsibility to process messages fast enough or
1007 to implement flow control. If an application does not process
1008 CORE messages fast enough, CORE will randomly drop messages
1009 to not keep a very long queue in memory.
1011 \exercise{Start one peer with a new service that has a message
1012 handler and start a second peer that only has your ``old'' service
1013 without message handlers. Which ``connect'' handlers are invoked when
1014 the two peers are connected? Why?}
1017 \subsection{Sending P2P Messages}
1019 You can transmit messages to other peers using the {\it mq} you were
1020 given during the {\tt connect} callback. Note that the {\it mq}
1021 automatically is released upon {\tt disconnect} and that you must
1022 not use it afterwards.
1024 It is your responsibility to not over-fill the message queue, GNUnet
1025 will send the messages roughly in the order given as soon as possible.
1027 \exercise{Write a service that upon connect sends messages as
1028 fast as possible to the other peer (the other peer should run a
1029 service that ``processes'' those messages). How fast is the
1030 transmission? Count using the STATISTICS service on both ends. Are
1031 messages lost? How can you transmit messages faster? What happens if
1032 you stop the peer that is receiving your messages?}
1035 \subsection{End of P2P connections}
1037 If a message handler returns {\tt GNUNET\_SYSERR}, the remote peer shuts down or
1038 there is an unrecoverable network disconnection, CORE notifies the service that
1039 the peer disconnected. After this notification no more messages will be received
1040 from the peer and the service is no longer allowed to send messages to the peer.
1041 The disconnect callback looks like the following:
1046 disconnects (void *cls,
1047 const struct GNUNET_PeerIdentity * peer)
1049 /* Remove peer's identity from known peers */
1050 /* Make sure no messages are sent to peer from now on */
1054 \exercise{Fix your service to handle peer disconnects.}
1056 \section{Storing peer-specific data using the PEERSTORE service}
1058 GNUnet's PEERSTORE service offers a persistorage for arbitrary peer-specific data.
1059 Other GNUnet services can use the PEERSTORE to store, retrieve and monitor data records.
1060 Each data record stored with PEERSTORE contains the following fields:
1064 \item subsystem: Name of the subsystem responsible for the record.
1065 \item peerid: Identity of the peer this record is related to.
1066 \item key: a key string identifying the record.
1067 \item value: binary record value.
1068 \item expiry: record expiry date.
1071 The first step is to start a connection to the PEERSTORE service:
1073 #include "gnunet_peerstore_service.h"
1075 peerstore_handle = GNUNET_PEERSTORE_connect (cfg);
1077 The service handle \lstinline|peerstore_handle| will be needed for all subsequent
1078 PEERSTORE operations.
1080 \subsection{Storing records}
1082 To store a new record, use the following function:
1084 struct GNUNET_PEERSTORE_StoreContext *
1085 GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
1086 const char *sub_system,
1087 const struct GNUNET_PeerIdentity *peer,
1091 struct GNUNET_TIME_Absolute expiry,
1092 enum GNUNET_PEERSTORE_StoreOption options,
1093 GNUNET_PEERSTORE_Continuation cont,
1097 The \lstinline|options| parameter can either be \lstinline|GNUNET_PEERSTORE_STOREOPTION_MULTIPLE|
1098 which means that multiple values can be stored under the same key combination (subsystem, peerid, key),
1099 or \lstinline|GNUNET_PEERSTORE_STOREOPTION_REPLACE| which means that PEERSTORE will replace any
1100 existing values under the given key combination (subsystem, peerid, key) with the new given value.
1102 The continuation function \lstinline|cont| will be called after the store request is successfully
1103 sent to the PEERSTORE service. This does not guarantee that the record is successfully stored, only
1104 that it was received by the service.
1106 The \lstinline|GNUNET_PEERSTORE_store| function returns a handle to the store operation. This handle
1107 can be used to cancel the store operation only before the continuation function is called:
1110 GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
1113 \subsection{Retrieving records}
1115 To retrieve stored records, use the following function:
1117 struct GNUNET_PEERSTORE_IterateContext *
1118 GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h,
1119 const char *sub_system,
1120 const struct GNUNET_PeerIdentity *peer,
1122 struct GNUNET_TIME_Relative timeout,
1123 GNUNET_PEERSTORE_Processor callback,
1124 void *callback_cls);
1126 The values of \lstinline|peer| and \lstinline|key| can be \lstinline|NULL|. This allows the
1127 iteration over values stored under any of the following key combinations:
1131 \item (subsystem, peerid)
1132 \item (subsystem, key)
1133 \item (subsystem, peerid, key)
1136 The \lstinline|callback| function will be called once with each retrieved record and once
1137 more with a \lstinline|NULL| record to signal the end of results.
1139 The \lstinline|GNUNET_PEERSTORE_iterate| function returns a handle to the iterate operation. This
1140 handle can be used to cancel the iterate operation only before the callback function is called with
1141 a \lstinline|NULL| record.
1143 \subsection{Monitoring records}
1145 PEERSTORE offers the functionality of monitoring for new records stored under a specific key
1146 combination (subsystem, peerid, key). To start the monitoring, use the following function:
1148 struct GNUNET_PEERSTORE_WatchContext *
1149 GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h,
1150 const char *sub_system,
1151 const struct GNUNET_PeerIdentity *peer,
1153 GNUNET_PEERSTORE_Processor callback,
1154 void *callback_cls);
1157 Whenever a new record is stored under the given key combination, the \lstinline|callback| function
1158 will be called with this new record. This will continue until the connection to the PEERSTORE service
1159 is broken or the watch operation is canceled:
1162 GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc);
1165 \subsection{Disconnecting from PEERSTORE}
1167 When the connection to the PEERSTORE service is no longer needed, disconnect using the following
1171 GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first);
1174 If the \lstinline|sync_first| flag is set to \lstinline|GNUNET_YES|, the API will delay the
1175 disconnection until all store requests are received by the PEERSTORE service. Otherwise,
1176 it will disconnect immediately.
1179 \section{Using the DHT}
1181 The DHT allows to store data so other peers in the P2P network can
1182 access it and retrieve data stored by any peers in the network.
1183 This section will explain how to use the DHT. Of course, the first
1184 thing to do is to connect to the DHT service:
1187 dht_handle = GNUNET_DHT_connect (cfg, parallel_requests);
1189 The second parameter indicates how many requests in parallel to expect.
1190 It is not a hard limit, but a good approximation will make the DHT more
1193 \subsection{Storing data in the DHT}
1194 Since the DHT is a dynamic environment (peers join and leave frequently)
1195 the data that we put in the DHT does not stay there indefinitely. It is
1196 important to ``refresh'' the data periodically by simply storing it again,
1197 in order to make sure other peers can access it.
1199 The put API call offers a callback to signal that the PUT request has been
1200 sent. This does not guarantee that the data is accessible to others peers,
1201 or even that is has been stored, only that the service has requested to
1202 a neighboring peer the retransmission of the PUT request towards its final
1203 destination. Currently there is no feedback about whether or not the data
1204 has been sucessfully stored or where it has been stored. In order to improve
1205 the availablilty of the data and to compensate for possible errors, peers leaving
1206 and other unfavorable events, just make several PUT requests!
1211 message_sent_cont (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
1213 // Request has left local node
1216 struct GNUNET_DHT_PutHandle *
1217 GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle,
1218 const struct GNUNET_HashCode *key,
1219 uint32_t desired_replication_level,
1220 enum GNUNET_DHT_RouteOption options,
1221 enum GNUNET_BLOCK_Type type, size_t size, const void *data,
1222 struct GNUNET_TIME_Absolute exp,
1223 struct GNUNET_TIME_Relative timeout,
1224 GNUNET_DHT_PutContinuation cont, void *cont_cls)
1227 \exercise{Store a value in the DHT periodically to make sure it is available
1228 over time. You might consider using the function GNUNET\_SCHEDULER\_add\_delayed and
1229 call GNUNET\_DHT\_put from inside a helper function.}
1232 \subsection{Obtaining data from the DHT}
1233 As we saw in the previous example, the DHT works in an asynchronous mode.
1234 Each request to the DHT is executed ``in the background'' and the API
1235 calls return immediately. In order to receive results from the DHT, the
1236 API provides a callback. Once started, the request runs in the service,
1237 the service will try to get as many results as possible (filtering out
1238 duplicates) until the timeout expires or we explicitly stop the request.
1239 It is possible to give a ``forever'' timeout with
1240 {\tt GNUNET\_TIME\_UNIT\_FOREVER\_REL}.
1242 If we give a route option {\tt GNUNET\_DHT\_RO\_RECORD\_ROUTE} the callback
1243 will get a list of all the peers the data has travelled, both on the PUT
1244 path and on the GET path.
1248 get_result_iterator (void *cls, struct GNUNET_TIME_Absolute expiration,
1249 const struct GNUNET_HashCode *key,
1250 const struct GNUNET_PeerIdentity *get_path,
1251 unsigned int get_path_length,
1252 const struct GNUNET_PeerIdentity *put_path,
1253 unsigned int put_path_length,
1254 enum GNUNET_BLOCK_Type type, size_t size, const void *data)
1257 GNUNET_DHT_get_stop (get_handle);
1261 GNUNET_DHT_get_start (dht_handle,
1268 &get_result_iterator,
1272 \exercise{Store a value in the DHT and after a while retrieve it. Show the IDs of all
1273 the peers the requests have gone through. In order to convert a peer ID to a string, use
1274 the function GNUNET\_i2s. Pay attention to the route option parameters in both calls!}
1276 \subsection{Implementing a block plugin}
1278 In order to store data in the DHT, it is necessary to provide a block
1279 plugin. The DHT uses the block plugin to ensure that only well-formed
1280 requests and replies are transmitted over the network.
1282 The block plugin should be put in a file {\tt
1283 plugin\_block\_SERVICE.c} in the service's respective directory. The
1284 mandatory functions that need to be implemented for a block plugin are
1285 described in the following sections.
1287 \subsubsection{Validating requests and replies}
1289 The evaluate function should validate a reply or a request. It returns
1290 a {\tt GNUNET\_BLOCK\_EvaluationResult}, which is an enumeration. All
1291 possible answers are in {\tt gnunet\_block\_lib.h}. The function will
1292 be called with a {\tt reply\_block} argument of {\tt NULL} for
1293 requests. Note that depending on how {\tt evaluate} is called, only
1294 some of the possible return values are valid. The specific meaning of
1295 the {\tt xquery} argument is application-specific. Applications that
1296 do not use an extended query should check that the {\tt xquery\_size}
1297 is zero. The block group is typically used to filter duplicate
1302 static enum GNUNET_BLOCK_EvaluationResult
1303 block_plugin_SERVICE_evaluate (void *cls,
1304 enum GNUNET_BLOCK_Type type,
1305 struct GNUNET_BlockGroup *bg,
1306 const GNUNET_HashCode *query,
1309 const void *reply_block,
1310 size_t reply_block_size)
1312 // Verify type, block and bg
1316 Note that it is mandatory to detect duplicate replies in this function
1317 and return the respective status code. Duplicate detection is
1318 typically done using the Bloom filter block group provided by {\tt
1319 libgnunetblockgroup.so}. Failure to do so may cause replies to
1320 circle in the network.
1322 \subsubsection{Deriving a key from a reply}
1324 The DHT can operate more efficiently if it is possible to derive a key
1325 from the value of the corresponding block. The {\tt get\_key}
1326 function is used to obtain the key of a block --- for example, by
1327 means of hashing. If deriving the key is not possible, the function
1328 should simply return {\tt GNUNET\_SYSERR} (the DHT will still work
1329 just fine with such blocks).
1334 block_plugin_SERVICE_get_key (void *cls, enum GNUNET_BLOCK_Type type,
1335 const void *block, size_t block_size,
1336 struct GNUNET_HashCode *key)
1338 // Store the key in the key argument, return GNUNET_OK on success.
1342 \subsubsection{Initialization of the plugin}
1344 The plugin is realized as a shared C library. The library must export
1345 an initialization function which should initialize the plugin. The
1346 initialization function specifies what block types the plugin cares
1347 about and returns a struct with the functions that are to be used for
1348 validation and obtaining keys (the ones just defined above).
1353 libgnunet_plugin_block_SERVICE_init (void *cls)
1355 static enum GNUNET_BLOCK_Type types[] =
1357 GNUNET_BLOCK_TYPE_SERVICE_BLOCKYPE,
1358 GNUNET_BLOCK_TYPE_ANY
1360 struct GNUNET_BLOCK_PluginFunctions *api;
1362 api = GNUNET_new (struct GNUNET_BLOCK_PluginFunctions);
1363 api->evaluate = &block_plugin_SERICE_evaluate;
1364 api->get_key = &block_plugin_SERVICE_get_key;
1370 \subsubsection{Shutdown of the plugin}
1372 Following GNUnet's general plugin API concept, the plugin must
1373 export a second function for cleaning up. It usually does very
1379 libgnunet_plugin_block_SERVICE_done (void *cls)
1381 struct GNUNET_TRANSPORT_PluginFunctions *api = cls;
1389 \subsubsection{Integration of the plugin with the build system}
1391 In order to compile the plugin, the {\tt Makefile.am} file for the
1392 service \texttt{SERVICE} should contain a rule similar to this:
1394 \lstset{language=make}
1396 plugindir = $(libdir)/gnunet
1398 plugin_LTLIBRARIES = \
1399 libgnunet_plugin_block_ext.la
1400 libgnunet_plugin_block_ext_la_SOURCES = \
1402 libgnunet_plugin_block_ext_la_LIBADD = \
1403 $(prefix)/lib/libgnunethello.la \
1404 $(prefix)/lib/libgnunetblock.la \
1405 $(prefix)/lib/libgnunetutil.la
1406 libgnunet_plugin_block_ext_la_LDFLAGS = \
1407 $(GN_PLUGIN_LDFLAGS)
1408 libgnunet_plugin_block_ext_la_DEPENDENCIES = \
1409 $(prefix)/lib/libgnunetblock.la
1414 \exercise{Write a block plugin that accepts all queries
1415 and all replies but prints information about queries and replies
1416 when the respective validation hooks are called.}
1420 \subsection{Monitoring the DHT}
1421 It is possible to monitor the functioning of the local DHT service. When monitoring
1422 the DHT, the service will alert the monitoring program of any events,
1423 both started locally or received for routing from another peer. The are three different
1424 types of events possible: a GET request, a PUT request or a response (a reply to
1427 Since the different events have different associated data, the API gets 3
1428 different callbacks (one for each message type) and optional type and key parameters,
1429 to allow for filtering of messages. When an event happens, the appropiate callback
1430 is called with all the information about the event.
1434 get_callback (void *cls,
1435 enum GNUNET_DHT_RouteOption options,
1436 enum GNUNET_BLOCK_Type type,
1438 uint32_t desired_replication_level,
1439 unsigned int path_length,
1440 const struct GNUNET_PeerIdentity *path,
1441 const struct GNUNET_HashCode * key)
1447 get_resp_callback (void *cls,
1448 enum GNUNET_BLOCK_Type type,
1449 const struct GNUNET_PeerIdentity *get_path,
1450 unsigned int get_path_length,
1451 const struct GNUNET_PeerIdentity *put_path,
1452 unsigned int put_path_length,
1453 struct GNUNET_TIME_Absolute exp,
1454 const struct GNUNET_HashCode * key,
1462 put_callback (void *cls,
1463 enum GNUNET_DHT_RouteOption options,
1464 enum GNUNET_BLOCK_Type type,
1466 uint32_t desired_replication_level,
1467 unsigned int path_length,
1468 const struct GNUNET_PeerIdentity *path,
1469 struct GNUNET_TIME_Absolute exp,
1470 const struct GNUNET_HashCode * key,
1477 monitor_handle = GNUNET_DHT_monitor_start (dht_handle,
1487 \section{Debugging with {\tt gnunet-arm}}
1489 Even if services are managed by {\tt gnunet-arm}, you can start them with
1490 {\tt gdb} or {\tt valgrind}. For example, you could add the following lines
1491 to your configuration file to start the DHT service in a {\tt gdb} session in a
1496 PREFIX=xterm -e gdb --args
1499 Alternatively, you can stop a service that was started via ARM and run it manually:
1501 \lstset{language=bash}
1504 $ gdb --args gnunet-service-dht -L DEBUG
1505 $ valgrind gnunet-service-dht -L DEBUG
1509 Assuming other services are well-written, they will automatically re-integrate the
1510 restarted service with the peer.
1512 GNUnet provides a powerful logging mechanism providing log levels \texttt{ERROR},
1513 \texttt{WARNING}, \texttt{INFO} and \texttt{DEBUG}. The current log level is
1514 configured using the \lstinline|$GNUNET_FORCE_LOG| environmental variable.
1515 The \texttt{DEBUG} level is only available if \lstinline|--enable-logging=verbose| was used when
1516 running \texttt{configure}. More details about logging can be found under
1517 \url{https://gnunet.org/logging}.
1519 You should also probably enable the creation of core files, by setting
1520 {\tt ulimit}, and echo'ing 1 into {\tt /proc/sys/kernel/core\_uses\_pid}.
1521 Then you can investigate the core dumps with {\tt gdb}, which is often
1522 the fastest method to find simple errors.
1524 \exercise{Add a memory leak to your service and obtain a trace
1525 pointing to the leak using {\tt valgrind} while running the service
1526 from {\tt gnunet-service-arm}.}