aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2014-04-07 18:50:35 +0000
committerChristian Grothoff <christian@grothoff.org>2014-04-07 18:50:35 +0000
commit9f2882bbd4e94f84f8fc97313fcf29aa3dc629db (patch)
tree9e160818bd479f6427beb07178bd0eb92ae0c8a8
parent274f395e7a8174292ded0db094180ad4731d24ff (diff)
downloadgnunet-9f2882bbd4e94f84f8fc97313fcf29aa3dc629db.tar.gz
gnunet-9f2882bbd4e94f84f8fc97313fcf29aa3dc629db.zip
-bump version in C tutorial
-rw-r--r--doc/gnunet-c-tutorial.pdfbin391250 -> 257638 bytes
-rw-r--r--doc/gnunet-c-tutorial.tex256
2 files changed, 140 insertions, 116 deletions
diff --git a/doc/gnunet-c-tutorial.pdf b/doc/gnunet-c-tutorial.pdf
index a8a98ce0c..da9eae74b 100644
--- a/doc/gnunet-c-tutorial.pdf
+++ b/doc/gnunet-c-tutorial.pdf
Binary files differ
diff --git a/doc/gnunet-c-tutorial.tex b/doc/gnunet-c-tutorial.tex
index 51da22db4..1142630cc 100644
--- a/doc/gnunet-c-tutorial.tex
+++ b/doc/gnunet-c-tutorial.tex
@@ -15,9 +15,9 @@
15 } 15 }
16 16
17 17
18\lstset{ 18\lstset{
19language=bash, 19language=bash,
20basicstyle=\ttfamily, 20basicstyle=\ttfamily,
21upquote=true, 21upquote=true,
22columns=fullflexible, 22columns=fullflexible,
23literate={*}{{\char42}}1 23literate={*}{{\char42}}1
@@ -29,39 +29,41 @@ literate={*}{{\char42}}1
29\begin{document} 29\begin{document}
30 30
31\begin{center} 31\begin{center}
32\large {A Tutorial for GNUnet 0.9.x (C version)} 32\large {A Tutorial for GNUnet 0.10.x (C version)}
33 33
34Christian Grothoff $\qquad$ Bart Polot $\qquad$ Matthias Wachs 34Christian Grothoff $\qquad$ Bart Polot $\qquad$ Matthias Wachs
35 35
36\today 36\today
37\end{center} 37\end{center}
38This tutorials explains how to install GNUnet on a GNU/Linux system and gives an introduction how 38This tutorials explains how to install GNUnet on a GNU/Linux system and gives an introduction how
39GNUnet can be used to develop a Peer-to-Peer application. Detailed installation instructions for 39GNUnet can be used to develop a Peer-to-Peer application. Detailed installation instructions for
40various operating systems and a detailed list of all dependencies can found on our website at 40various operating systems and a detailed list of all dependencies can found on our website at
41\url{https://gnunet.org/installation}. 41\url{https://gnunet.org/installation}.
42 42
43\textbf{Please read this tutorial carefully since every single step is 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: 43\textbf{Please read this tutorial carefully since every single step is
44\url{https://gnunet.org/contact_information}} 44 important and do not hesitate to contact the GNUnet team if you have
45 any questions or problems! Check here how to contact the GNUnet
46 team: \url{https://gnunet.org/contact_information}}
45 47
46 48
47\section{Installing GNUnet} 49\section{Installing GNUnet}
48First of all you have to install a current version of GNUnet. You can download a 50First of all you have to install a current version of GNUnet. You can download a
49tarball of a stable version from GNU FTP mirrors or obtain the latest development 51tarball of a stable version from GNU FTP mirrors or obtain the latest development
50version from our Subversion repository. 52version from our Subversion repository.
51 53
52Most of the time you should prefer to download the stable version since with the 54Most of the time you should prefer to download the stable version since with the
53latest development version things can be broken, functionality can be changed or tests 55latest development version things can be broken, functionality can be changed or tests
54can fail. You should only use the development version if you know that you require a 56can fail. You should only use the development version if you know that you require a
55certain feature or a certain issue has been fixed since the last release. 57certain feature or a certain issue has been fixed since the last release.
56 58
57\subsection{Obtaining a stable version} 59\subsection{Obtaining a stable version}
58You can download the latest stable version of GNUnet from GNU FTP mirrors: 60You can download the latest stable version of GNUnet from GNU FTP mirrors:
59\begin{center} 61\begin{center}
60\url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.9.5a.tar.gz} 62\url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz}
61\end{center} 63\end{center}
62You should also download the signature file and verify the integrity of the tarball. 64You should also download the signature file and verify the integrity of the tarball.
63\begin{center} 65\begin{center}
64\url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.9.5a.tar.gz.sig} 66\url{ftp://ftp.gnu.org/gnu/gnunet/gnunet-0.10.x.tar.gz.sig}
65\end{center} 67\end{center}
66To verify the signature you should first import the GPG key used to sign the tarball 68To verify the signature you should first import the GPG key used to sign the tarball
67\begin{lstlisting} 69\begin{lstlisting}
@@ -69,28 +71,28 @@ $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E
69\end{lstlisting} 71\end{lstlisting}
70And use this key to verify the tarball's signature 72And use this key to verify the tarball's signature
71\begin{lstlisting} 73\begin{lstlisting}
72$ gpg --verify gnunet-0.9.5a.tar.gz.sig gnunet-0.9.5a.tar.gz 74$ gpg --verify gnunet-0.10.x.tar.gz.sig gnunet-0.10.x.tar.gz
73\end{lstlisting} 75\end{lstlisting}
74After successfully verifying the integrity you can extract the tarball using 76After successfully verifying the integrity you can extract the tarball using
75\begin{lstlisting} 77\begin{lstlisting}
76$ tar xvzf gnunet-0.9.5a.tar.gz 78$ tar xvzf gnunet-0.10.x.tar.gz
77$ mv gnunet-0.9.5a gnunet # we will use the directory "gnunet" in the remainder of this document 79$ mv gnunet-0.10.x gnunet # we will use the directory "gnunet" in the remainder of this document
78$ cd gnunet 80$ cd gnunet
79\end{lstlisting} 81\end{lstlisting}
80 82
81\subsection{Installing Build Tool Chain and Dependencies} 83\subsection{Installing Build Tool Chain and Dependencies}
82To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies. 84To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies.
83Please have a look at \url{https://gnunet.org/dependencies} for a list of required dependencies 85Please have a look at \url{https://gnunet.org/dependencies} for a list of required dependencies
84and \url{https://gnunet.org/generic_installation} for specific instructions for your operating system. 86and \url{https://gnunet.org/generic_installation} for specific instructions for your operating system.
85 87
86Please check the notes at the end of the configure process about required dependencies. 88Please check the notes at the end of the configure process about required dependencies.
87 89
88For GNUNet bootstrapping support and the http(s) plugin you should install \texttt{libcurl}. 90For GNUNet bootstrapping support and the http(s) plugin you should install \texttt{libcurl}.
89For the filesharing service you should install at least one of the datastore backends \texttt{mysql}, 91For the filesharing service you should install at least one of the datastore backends \texttt{mysql},
90\texttt{sqlite} or \texttt{postgresql}. 92\texttt{sqlite} or \texttt{postgresql}.
91 93
92\subsection{Obtaining the latest version from Subversion} 94\subsection{Obtaining the latest version from Subversion}
93The latest development version can obtained from our Subversion (\textit{svn}) repository. To obtain 95The latest development version can obtained from our Subversion (\textit{svn}) repository. To obtain
94the code you need Subversion installed and checkout the repository using: 96the code you need Subversion installed and checkout the repository using:
95\lstset{language=bash} 97\lstset{language=bash}
96\begin{lstlisting} 98\begin{lstlisting}
@@ -107,8 +109,10 @@ The remainder of this tutorial assumes that you have SVN HEAD checked out.
107 109
108\subsection{Compiling and Installing GNUnet} 110\subsection{Compiling and Installing GNUnet}
109 111
110First, you need to install at least {\tt 112First, you need to install at least {\tt libgnupgerror} version
111 libgnupgerror} version 1.12\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2}}and {\tt libgcrypt} version 1.6\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2}}. 1131.12\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgpg-error/libgpg-error-1.12.tar.bz2}}
114and {\tt libgcrypt} version
1151.6\footnote{\url{ftp://ftp.gnupg.org/gcrypt/libgcrypt/libgcrypt-1.6.0.tar.bz2}}.
112 116
113\lstset{language=bash} 117\lstset{language=bash}
114\begin{lstlisting} 118\begin{lstlisting}
@@ -131,23 +135,35 @@ $ cd ..
131\end{lstlisting} 135\end{lstlisting}
132 136
133\label{sub:install} 137\label{sub:install}
134Assuming all dependencies are installed, the following commands will compile and install GNUnet in your 138Assuming all dependencies are installed, the following commands will
135home directory. You can specify the directory where GNUnet will be installed by changing the \lstinline|--prefix| value when calling \lstinline|./configure|. If you do not specifiy a prefix, GNUnet is installed in the directory \lstinline|/usr/local|. When developing new applications you may want to enable 139compile and install GNUnet in your home directory. You can specify the
136verbose logging by adding \lstinline|--enable-logging=verbose|: 140directory where GNUnet will be installed by changing the
141\lstinline|--prefix| value when calling \lstinline|./configure|. If
142you do not specifiy a prefix, GNUnet is installed in the directory
143\lstinline|/usr/local|. When developing new applications you may want
144to enable verbose logging by adding
145\lstinline|--enable-logging=verbose|:
137 146
138\lstset{language=bash} 147\lstset{language=bash}
139\begin{lstlisting} 148\begin{lstlisting}
140$ ./configure --prefix=$HOME --enable-logging 149$ ./configure --prefix=$HOME --enable-logging
141$ make 150$ make
142$ make install 151$ make install
143\end{lstlisting} 152\end{lstlisting}
144 153
145After installing GNUnet you have to set the \lstinline|GNUNET_PREFIX| environmental variable used by GNUnet to detect it's installation directory and add your GNUnet installation to your path environmental variable. 154After installing GNUnet you have to set the \lstinline|GNUNET_PREFIX|
146This configuration is only valid for the current shell session, so you should add \lstinline|export GNUNET_PREFIX=$HOME| to your \lstinline|.bash_rc| or \lstinline|.profile| to be sure the environment variable is always set. In addition you have to create the \lstinline|.gnunet| directory in your home directory where GNUnet stores it's data and an empty GNUnet configuration file: 155environmental variable used by GNUnet to detect it's installation
156directory and add your GNUnet installation to your path environmental
157variable. This configuration is only valid for the current shell
158session, so you should add \lstinline|export GNUNET_PREFIX=$HOME| to
159your \lstinline|.bash_rc| or \lstinline|.profile| to be sure the
160environment variable is always set. In addition you have to create the
161\lstinline|.gnunet| directory in your home directory where GNUnet
162stores it's data and an empty GNUnet configuration file:
147 163
148\lstset{language=bash} 164\lstset{language=bash}
149\begin{lstlisting} 165\begin{lstlisting}
150$ export GNUNET_PREFIX=$HOME 166$ export GNUNET_PREFIX=$HOME
151$ export PATH=$PATH:$GNUNET_PREFIX/bin 167$ export PATH=$PATH:$GNUNET_PREFIX/bin
152$ echo export GNUNET_PREFIX=$HOME >> ~/.bashrc 168$ echo export GNUNET_PREFIX=$HOME >> ~/.bashrc
153$ echo export PATH=$GNUNET_PREFIX/bin:$PATH >> ~/.bashrc 169$ echo export PATH=$GNUNET_PREFIX/bin:$PATH >> ~/.bashrc
@@ -157,14 +173,18 @@ $ touch ~/.gnunet/gnunet.conf
157% $ 173% $
158 174
159\subsection{Common Issues - Check your GNUnet installation} 175\subsection{Common Issues - Check your GNUnet installation}
160You should check your installation to ensure that installing GNUnet was successful up to this point. You should be able to access GNUnet's binaries and run GNUnet's self check. 176You should check your installation to ensure that installing GNUnet
177was successful up to this point. You should be able to access GNUnet's
178binaries and run GNUnet's self check.
161\begin{lstlisting} 179\begin{lstlisting}
162$ which gnunet-arm 180$ which gnunet-arm
163\end{lstlisting} 181\end{lstlisting}
164should return \lstinline|$GNUNET_PREFIX/bin/gnunet-arm|. It should be located in your GNUnet installation and the output should not be empty. If you see an output like: 182should return \lstinline|$GNUNET_PREFIX/bin/gnunet-arm|. It should be
183located in your GNUnet installation and the output should not be
184empty. If you see an output like:
165\begin{lstlisting} 185\begin{lstlisting}
166$ which gnunet-arm 186$ which gnunet-arm
167$ 187$
168\end{lstlisting} 188\end{lstlisting}
169check your {\tt PATH} variable to ensure GNUnet's {\tt bin} directory is included. 189check your {\tt PATH} variable to ensure GNUnet's {\tt bin} directory is included.
170 190
@@ -172,7 +192,7 @@ GNUnet provides tests for all of it's subcomponents. Run
172\begin{lstlisting} 192\begin{lstlisting}
173$ make check 193$ make check
174\end{lstlisting} 194\end{lstlisting}
175to execute tests for all components. {\tt make check} traverses all subdirectories in {\tt src}. 195to execute tests for all components. {\tt make check} traverses all subdirectories in {\tt src}.
176For every subdirectory you should get a message like this: 196For every subdirectory you should get a message like this:
177 197
178\begin{lstlisting} 198\begin{lstlisting}
@@ -195,9 +215,9 @@ double check your {\tt GNUNET\_PREFIX} environmental variable and double check t
195 215
196\section{Background: GNUnet Architecture} 216\section{Background: GNUnet Architecture}
197GNUnet is organized in layers and services. Each service is composed of a 217GNUnet is organized in layers and services. Each service is composed of a
198main service implementation and a client library for other programs to use 218main service implementation and a client library for other programs to use
199the service's functionality, described by an API. This approach is shown in 219the service's functionality, described by an API. This approach is shown in
200figure~\ref{fig:service}. Some services provide an additional command line 220figure~\ref{fig:service}. Some services provide an additional command line
201tool to enable the user to interact with the service. 221tool to enable the user to interact with the service.
202 222
203Very often it is other GNUnet services that will use these APIs to build the 223Very often it is other GNUnet services that will use these APIs to build the
@@ -213,14 +233,14 @@ a DHT). See figure ~\ref{fig:interaction} for an illustration of this approach.
213 \includegraphics[width=\textwidth]{figs/Service.pdf} 233 \includegraphics[width=\textwidth]{figs/Service.pdf}
214 \caption{Service with API and network protocol} 234 \caption{Service with API and network protocol}
215 \label{fig:service} 235 \label{fig:service}
216 \end{subfigure} 236 \end{subfigure}
217 ~~~~~~~~~~ 237 ~~~~~~~~~~
218 \begin{subfigure}[b]{0.3\textwidth} 238 \begin{subfigure}[b]{0.3\textwidth}
219 \centering 239 \centering
220 \includegraphics[width=\textwidth]{figs/System.pdf} 240 \includegraphics[width=\textwidth]{figs/System.pdf}
221 \caption{Service interaction} 241 \caption{Service interaction}
222 \label{fig:interaction} 242 \label{fig:interaction}
223 \end{subfigure} 243 \end{subfigure}
224 \end{center} 244 \end{center}
225 \caption{GNUnet's layered system architecture} 245 \caption{GNUnet's layered system architecture}
226\end{figure} 246\end{figure}
@@ -236,15 +256,17 @@ the programmer.
236\subsection{Configure your peer} 256\subsection{Configure your peer}
237First of all we need to configure your peer. Each peer is started with a configuration containing settings for GNUnet itself and it's services. This configuration is based on the default configuration shipped with GNUnet and can be modified. The default configuration is located in the {\tt \$GNUNET\_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. 257First of all we need to configure your peer. Each peer is started with a configuration containing settings for GNUnet itself and it's services. This configuration is based on the default configuration shipped with GNUnet and can be modified. The default configuration is located in the {\tt \$GNUNET\_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.
238 258
239Since we want to start additional peers later, we need 259Since we want to start additional peers later, we need
240some modifications from the default configuration. We need to create a separate service home and a file containing our modifications for this peer: 260some modifications from the default configuration. We need to create a separate service home and a file containing our modifications for this peer:
241\begin{lstlisting} 261\begin{lstlisting}
242$ mkdir ~/gnunet1/ 262$ mkdir ~/gnunet1/
243$ touch peer1.conf 263$ touch peer1.conf
244\end{lstlisting} 264\end{lstlisting}
245 265
246Now add the following lines to peer1.conf to use this directory. For simplified usage we want to prevent 266Now add the following lines to peer1.conf to use this directory. For
247the peer to connect to the GNUnet network since this could lead to confusing output. This modifications will replace the default settings: 267simplified usage we want to prevent the peer to connect to the GNUnet
268network since this could lead to confusing output. This modifications
269will replace the default settings:
248\begin{lstlisting} 270\begin{lstlisting}
249[PATHS] 271[PATHS]
250GNUNET_HOME = ~/gnunet1/ # Use this directory to store GNUnet data 272GNUNET_HOME = ~/gnunet1/ # Use this directory to store GNUnet data
@@ -253,9 +275,9 @@ SERVERS = # prevent bootstrapping
253\end{lstlisting} 275\end{lstlisting}
254 276
255\subsection{Start a peer} 277\subsection{Start a peer}
256Each GNUnet instance (called peer) has an identity (\textit{peer ID}) based on a 278Each GNUnet instance (called peer) has an identity (\textit{peer ID}) based on a
257cryptographic public private key pair. The peer ID is the printable hash of the 279cryptographic public private key pair. The peer ID is the printable hash of the
258public key. So before starting the peer, you may want to just generate the peer's private 280public key. So before starting the peer, you may want to just generate the peer's private
259key using the command 281key using the command
260\lstset{language=bash} 282\lstset{language=bash}
261\begin{lstlisting} 283\begin{lstlisting}
@@ -269,16 +291,16 @@ I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
269 291
270GNUnet services are controlled by a master service the so called \textit{Automatic Restart Manager} (ARM). 292GNUnet services are controlled by a master service the so called \textit{Automatic Restart Manager} (ARM).
271ARM starts, stops and even restarts services automatically or on demand when a client connects. 293ARM starts, stops and even restarts services automatically or on demand when a client connects.
272You interact with the ARM service using the \lstinline|gnunet-arm| tool. 294You interact with the ARM service using the \lstinline|gnunet-arm| tool.
273GNUnet can then be started with \lstinline|gnunet-arm -s| and stopped with 295GNUnet can then be started with \lstinline|gnunet-arm -s| and stopped with
274\lstinline|gnunet-arm -e|. An additional service not automatically started 296\lstinline|gnunet-arm -e|. An additional service not automatically started
275can be started using \lstinline|gnunet-arm -i <service name>| and stopped 297can be started using \lstinline|gnunet-arm -i <service name>| and stopped
276using \lstinline|gnunet-arm -k <servicename>|. 298using \lstinline|gnunet-arm -k <servicename>|.
277 299
278\subsection{Monitor a peer} 300\subsection{Monitor a peer}
279In this section, we will monitor the behaviour of our peer's DHT service with respect to a 301In this section, we will monitor the behaviour of our peer's DHT service with respect to a
280specific key. First we will start GNUnet and then start the DHT service and use the DHT monitor tool 302specific key. First we will start GNUnet and then start the DHT service and use the DHT monitor tool
281to monitor the PUT and GET commands we issue ussing the \lstinline|gnunet-dht-put| and 303to monitor the PUT and GET commands we issue ussing the \lstinline|gnunet-dht-put| and
282\lstinline|gnunet-dht-get| command. Using the ``monitor'' line given below, you can observe the behavior of 304\lstinline|gnunet-dht-get| command. Using the ``monitor'' line given below, you can observe the behavior of
283your own peer's DHT with respect to the specified KEY: 305your own peer's DHT with respect to the specified KEY:
284 306
@@ -292,7 +314,7 @@ $ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY
292Now open a separate terminal and change again to the \lstinline|gnunet/src/dht| directory: 314Now open a separate terminal and change again to the \lstinline|gnunet/src/dht| directory:
293\begin{lstlisting} 315\begin{lstlisting}
294$ cd ~/gnunet/src/dht 316$ cd ~/gnunet/src/dht
295$ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE # put VALUE under KEY in the DHT 317$ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE # put VALUE under KEY in the DHT
296$ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY # get key KEY from the DHT 318$ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY # get key KEY from the DHT
297$ gnunet-statistics -c ~/peer1.conf # print statistics about current GNUnet state 319$ gnunet-statistics -c ~/peer1.conf # print statistics about current GNUnet state
298$ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service 320$ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service
@@ -302,10 +324,10 @@ $ gnunet-statistics -c ~/peer1.conf -s dht # print statistics about DHT service
302\subsubsection{Setup a second peer} 324\subsubsection{Setup a second peer}
303We will now start a second peer on your machine. 325We will now start a second peer on your machine.
304For the second peer, you will need to manually create a modified 326For the second peer, you will need to manually create a modified
305configuration file to avoid conflicts with ports and directories. 327configuration file to avoid conflicts with ports and directories.
306A peers configuration file is by default located in {\tt ~/.gnunet/gnunet.conf}. 328A peers configuration file is by default located in {\tt ~/.gnunet/gnunet.conf}.
307This file is typically very short or even empty as only the differences to the 329This file is typically very short or even empty as only the differences to the
308defaults need to be specified. The defaults are located in 330defaults need to be specified. The defaults are located in
309many files in the {\tt \$GNUNET\_PREFIX/share/gnunet/config.d} directory. 331many files in the {\tt \$GNUNET\_PREFIX/share/gnunet/config.d} directory.
310 332
311To configure the second peer, use the files {\tt 333To configure the second peer, use the files {\tt
@@ -321,7 +343,7 @@ Now you have to edit {\tt peer2.conf} and change:
321 \itemsep0em 343 \itemsep0em
322 \item{\texttt{SERVICEHOME} under \texttt{PATHS}} 344 \item{\texttt{SERVICEHOME} under \texttt{PATHS}}
323 \item{Every (uncommented) value for ``\texttt{PORT}'' (add 10000) in any 345 \item{Every (uncommented) value for ``\texttt{PORT}'' (add 10000) in any
324 section (the option may be commented out if \texttt{PORT} is 346 section (the option may be commented out if \texttt{PORT} is
325 prefixed by "\#", in this case, UNIX domain sockets are used 347 prefixed by "\#", in this case, UNIX domain sockets are used
326 and the PORT option does not need to be touched) } 348 and the PORT option does not need to be touched) }
327 \item{Every value for ``\texttt{UNIXPATH}'' in any section (e.g. by adding a "-p2" suffix)} 349 \item{Every value for ``\texttt{UNIXPATH}'' in any section (e.g. by adding a "-p2" suffix)}
@@ -360,7 +382,9 @@ If you want the two peers to connect, you have multiple options:
360 \item Setup a bootstrap server 382 \item Setup a bootstrap server
361 \item Connect manually 383 \item Connect manually
362\end{itemize} 384\end{itemize}
363To setup peer 1 as bootstrapping server change the configuration of the first one to be a hostlist server by adding the following lines to \texttt{peer1.conf} to enable bootstrapping server: 385To setup peer 1 as bootstrapping server change the configuration of
386the first one to be a hostlist server by adding the following lines to
387\texttt{peer1.conf} to enable bootstrapping server:
364 \begin{lstlisting} 388 \begin{lstlisting}
365[hostlist] 389[hostlist]
366OPTIONS = -p 390OPTIONS = -p
@@ -377,7 +401,7 @@ $ gnunet-arm -c peer2.conf -s # start second peer
377Note that if you start your peers without changing these settings, they 401Note that if you start your peers without changing these settings, they
378will use the ``global'' hostlist servers of the GNUnet P2P network and 402will use the ``global'' hostlist servers of the GNUnet P2P network and
379likely connect to those peers. At that point, debugging might become 403likely connect to those peers. At that point, debugging might become
380tricky as you're going to be connected to many more peers and would 404tricky as you're going to be connected to many more peers and would
381likely observe traffic and behaviors that are not explicitly controlled 405likely observe traffic and behaviors that are not explicitly controlled
382by you. 406by you.
383 407
@@ -391,7 +415,7 @@ If you want to use the \texttt{peerinfo} tool to connect your peers, you should:
391 \item{Give the output to the second peer by running {\tt gnunet-peerinfo -c peer2.conf -p '<output>'}} 415 \item{Give the output to the second peer by running {\tt gnunet-peerinfo -c peer2.conf -p '<output>'}}
392\end{itemize} 416\end{itemize}
393 417
394Check that they are connected using {\tt gnunet-core -c peer1.conf}, which should give you the other peer's 418Check that they are connected using {\tt gnunet-core -c peer1.conf}, which should give you the other peer's
395peer identity: 419peer identity:
396\begin{lstlisting} 420\begin{lstlisting}
397$ gnunet-core -c peer1.conf 421$ gnunet-core -c peer1.conf
@@ -416,7 +440,7 @@ This function takes a configuration file which will be used as a template
416configuration for the peers. The testbed takes care of modifying relevant 440configuration for the peers. The testbed takes care of modifying relevant
417options in the peers' configuration such as SERVICEHOME, PORT, UNIXPATH to 441options in the peers' configuration such as SERVICEHOME, PORT, UNIXPATH to
418unique values so that peers run without running into conflicts. It also checks 442unique values so that peers run without running into conflicts. It also checks
419and assigns the ports in configurations only if they are free. 443and assigns the ports in configurations only if they are free.
420 444
421Additionally, the testbed service also reads its options from the same 445Additionally, the testbed service also reads its options from the same
422configuration file. Various available options and details about them can be 446configuration file. Various available options and details about them can be
@@ -506,7 +530,7 @@ remainder of this document. The functionality of a GNUnet service is implemented
506\itemsep0em 530\itemsep0em
507 \item the GNUnet service (\lstinline|gnunet-ext/src/ext/gnunet-service-ext.c|) 531 \item the GNUnet service (\lstinline|gnunet-ext/src/ext/gnunet-service-ext.c|)
508 \item the client API (\lstinline|gnunet-ext/src/ext/ext_api.c|) 532 \item the client API (\lstinline|gnunet-ext/src/ext/ext_api.c|)
509 \item the client application using the service API (\lstinline|gnunet-ext/src/ext/gnunet-ext.c|) 533 \item the client application using the service API (\lstinline|gnunet-ext/src/ext/gnunet-ext.c|)
510 534
511 535
512\end{itemize} 536\end{itemize}
@@ -514,7 +538,7 @@ remainder of this document. The functionality of a GNUnet service is implemented
514The interfaces for these entities are defined in: 538The interfaces for these entities are defined in:
515\begin{itemize} 539\begin{itemize}
516\itemsep0em 540\itemsep0em
517 \item client API interface (\lstinline|gnunet-ext/src/ext/ext.h|) 541 \item client API interface (\lstinline|gnunet-ext/src/ext/ext.h|)
518 \item the service interface (\lstinline|gnunet-ext/src/include/gnunet_service_SERVICE.h|) 542 \item the service interface (\lstinline|gnunet-ext/src/include/gnunet_service_SERVICE.h|)
519 \item the P2P protocol (\lstinline|gnunet-ext/src/include/gnunet_protocols_ext.h|) 543 \item the P2P protocol (\lstinline|gnunet-ext/src/include/gnunet_protocols_ext.h|)
520\end{itemize} 544\end{itemize}
@@ -533,10 +557,10 @@ In addition the \texttt{ext} systems provides:
533The first step for writing any extension with a new service is to 557The first step for writing any extension with a new service is to
534ensure that the {\tt ext.conf.in} file contains entries for the 558ensure that the {\tt ext.conf.in} file contains entries for the
535\texttt{UNIXPATH}, \texttt{PORT} and \texttt{BINARY} for the service in a section named after 559\texttt{UNIXPATH}, \texttt{PORT} and \texttt{BINARY} for the service in a section named after
536the service. 560the service.
537 561
538If you want to adapt the template rename the {\tt ext.conf.in} to match your 562If you want to adapt the template rename the {\tt ext.conf.in} to match your
539services name, you have to modify the \texttt{AC\_OUTPUT} section in {\tt configure.ac} 563services name, you have to modify the \texttt{AC\_OUTPUT} section in {\tt configure.ac}
540in the \texttt{gnunet-ext} root. 564in the \texttt{gnunet-ext} root.
541 565
542\section{Writing a Client Application} 566\section{Writing a Client Application}
@@ -612,9 +636,9 @@ the {\tt --help} argument and error handling are taken care of when
612using this approach. Other {\tt GNUNET\_GETOPT\_}-functions can be used 636using this approach. Other {\tt GNUNET\_GETOPT\_}-functions can be used
613to obtain integer value options, increment counters, etc. You can 637to obtain integer value options, increment counters, etc. You can
614even write custom option parsers for special circumstances not covered 638even write custom option parsers for special circumstances not covered
615by the available handlers. To check if an argument was specified by the 639by the available handlers. To check if an argument was specified by the
616user you initialize the variable with a specific value (e.g. NULL for 640user you initialize the variable with a specific value (e.g. NULL for
617a string and GNUNET\_SYSERR for a integer) and check after parsing 641a string and GNUNET\_SYSERR for a integer) and check after parsing
618happened if the values were modified. 642happened if the values were modified.
619 643
620Inside the {\tt run} method, the program would perform the 644Inside the {\tt run} method, the program would perform the
@@ -629,7 +653,7 @@ of {\tt run}. What happens if the user gives invalid arguments?}
629\subsection{Writing a Client Library} 653\subsection{Writing a Client Library}
630 654
631The first and most important step in writing a client library is to 655The first and most important step in writing a client library is to
632decide on an API for the library. Typical API calls include 656decide on an API for the library. Typical API calls include
633connecting to the service, performing application-specific requests 657connecting to the service, performing application-specific requests
634and cleaning up. Many examples for such service APIs can be found 658and cleaning up. Many examples for such service APIs can be found
635in the {\tt gnunet/src/include/gnunet\_*\_service.h} files. 659in the {\tt gnunet/src/include/gnunet\_*\_service.h} files.
@@ -658,14 +682,14 @@ with the service, a connection must be created:
658 client = GNUNET_CLIENT_connect ("service-name", cfg); 682 client = GNUNET_CLIENT_connect ("service-name", cfg);
659\end{lstlisting} 683\end{lstlisting}
660 684
661As a result a {\tt GNUNET\_CLIENT\_Connection} handle is returned 685As a result a {\tt GNUNET\_CLIENT\_Connection} handle is returned
662which has to used in later API calls related to this service. 686which has to used in later API calls related to this service.
663The complete client API can be found in {\tt gnunet\_client\_lib.h} 687The complete client API can be found in {\tt gnunet\_client\_lib.h}
664 688
665\subsubsection{GNUnet Messages} 689\subsubsection{GNUnet Messages}
666 690
667In GNUnet, messages are always sent beginning with a {\tt struct GNUNET\_MessageHeader} 691In GNUnet, messages are always sent beginning with a {\tt struct GNUNET\_MessageHeader}
668in big endian format. This header defines the size and the type of the 692in big endian format. This header defines the size and the type of the
669message, the payload follows after this header. 693message, the payload follows after this header.
670 694
671\lstset{language=c} 695\lstset{language=c}
@@ -692,7 +716,7 @@ A common way to create a message is:
692 716
693\lstset{language=c} 717\lstset{language=c}
694\begin{lstlisting} 718\begin{lstlisting}
695struct GNUNET_MessageHeader *msg = 719struct GNUNET_MessageHeader *msg =
696 GNUNET_malloc(payload_size + sizeof(struct GNUNET_MessageHeader)); 720 GNUNET_malloc(payload_size + sizeof(struct GNUNET_MessageHeader));
697msg->size = htons(payload_size + sizeof(struct GNUNET_MessageHeader)); 721msg->size = htons(payload_size + sizeof(struct GNUNET_MessageHeader));
698msg->type = htons(GNUNET_MY_MESSAGE_TYPE); 722msg->type = htons(GNUNET_MY_MESSAGE_TYPE);
@@ -727,7 +751,7 @@ transmit_cb (void *cls, size_t size, void *buf)
727 return msg_size; 751 return msg_size;
728} 752}
729 753
730// ... 754// ...
731th = GNUNET_CLIENT_notify_transmit_ready (client, 755th = GNUNET_CLIENT_notify_transmit_ready (client,
732 msg_size, 756 msg_size,
733 timeout, 757 timeout,
@@ -737,17 +761,17 @@ th = GNUNET_CLIENT_notify_transmit_ready (client,
737\end{lstlisting} 761\end{lstlisting}
738 762
739The client-service protocoll calls {\tt GNUNET\_CLIENT\_notify\_transmit\_ready} 763The client-service protocoll calls {\tt GNUNET\_CLIENT\_notify\_transmit\_ready}
740to be notified when the client is ready to send data to the service. 764to be notified when the client is ready to send data to the service.
741Besides other arguments, you have to pass the client returned 765Besides other arguments, you have to pass the client returned
742from the {\tt connect} call, the message size and the callback function to 766from the {\tt connect} call, the message size and the callback function to
743call when the client is ready to send. 767call when the client is ready to send.
744 768
745Only a single transmission request can be queued per client at the 769Only a single transmission request can be queued per client at the
746same time using this API. The handle {\tt th} can be used to cancel 770same time using this API. The handle {\tt th} can be used to cancel
747the request if necessary (for example, during shutdown). 771the request if necessary (for example, during shutdown).
748 772
749When {\tt transmit\_cb} is called the message is copied in the buffer provided and 773When {\tt transmit\_cb} is called the message is copied in the buffer provided and
750the number of bytes copied into the buffer is returned. {\tt transmit\_cb} 774the number of bytes copied into the buffer is returned. {\tt transmit\_cb}
751could also return 0 if for some reason no message 775could also return 0 if for some reason no message
752could be constructed; this is not an error and the connection to the 776could be constructed; this is not an error and the connection to the
753service will persist in this case. 777service will persist in this case.
@@ -778,7 +802,7 @@ receive_message (void *cls, const struct GNUNET_MessageHeader *msg)
778 // process 'msg' 802 // process 'msg'
779} 803}
780 804
781// ... 805// ...
782 GNUNET_CLIENT_receive (client, 806 GNUNET_CLIENT_receive (client,
783 &receive_message, 807 &receive_message,
784 arg, 808 arg,
@@ -793,7 +817,7 @@ message. To receive additional messages, {\tt
793\exercise{Expand your helper function to receive a 817\exercise{Expand your helper function to receive a
794response message (for example, containing just the GNUnet MessageHeader 818response message (for example, containing just the GNUnet MessageHeader
795without any payload). Upon receiving the service's response, you should 819without any payload). Upon receiving the service's response, you should
796call a callback provided to your helper function's API. You'll need to 820call a callback provided to your helper function's API. You'll need to
797define a new 'struct' to hold your local context (``closure'').} 821define a new 'struct' to hold your local context (``closure'').}
798 822
799 823
@@ -809,7 +833,7 @@ For example, send a 32-bit integer value based on a number given
809at the command-line to the service.} 833at the command-line to the service.}
810 834
811 835
812 836
813\section{Writing a Service} 837\section{Writing a Service}
814 838
815Before you can test the client you've written so far, you'll need to also 839Before you can test the client you've written so far, you'll need to also
@@ -848,18 +872,18 @@ Here is a starting point for your main function for your service:
848static void my_main (void *cls, 872static void my_main (void *cls,
849 struct GNUNET_SERVER_Handle *server, 873 struct GNUNET_SERVER_Handle *server,
850 const struct GNUNET_CONFIGURATION_Handle *cfg) 874 const struct GNUNET_CONFIGURATION_Handle *cfg)
851{ 875{
852 /* do work */ 876 /* do work */
853} 877}
854 878
855int main (int argc, char *const*argv) 879int main (int argc, char *const*argv)
856{ 880{
857 if (GNUNET_OK != 881 if (GNUNET_OK !=
858 GNUNET_SERVICE_run (argc, argv, "my", 882 GNUNET_SERVICE_run (argc, argv, "my",
859 GNUNET_SERVICE_OPTION_NONE, 883 GNUNET_SERVICE_OPTION_NONE,
860 &my_main, NULL); 884 &my_main, NULL);
861 return 1; 885 return 1;
862 return 0; 886 return 0;
863} 887}
864\end{lstlisting} 888\end{lstlisting}
865 889
@@ -883,28 +907,28 @@ handle_set (void *cls,
883 struct GNUNET_SERVER_Client *client, 907 struct GNUNET_SERVER_Client *client,
884 const struct GNUNET_MessageHeader *message) 908 const struct GNUNET_MessageHeader *message)
885{ 909{
886 GNUNET_SERVER_receive_done (client, GNUNET_OK); 910 GNUNET_SERVER_receive_done (client, GNUNET_OK);
887} 911}
888static void 912static void
889handle_get (void *cls, 913handle_get (void *cls,
890 struct GNUNET_SERVER_Client *client, 914 struct GNUNET_SERVER_Client *client,
891 const struct GNUNET_MessageHeader *message) 915 const struct GNUNET_MessageHeader *message)
892{ 916{
893 GNUNET_SERVER_receive_done (client, GNUNET_OK); 917 GNUNET_SERVER_receive_done (client, GNUNET_OK);
894} 918}
895 919
896static void my_main (void *cls, 920static void my_main (void *cls,
897 struct GNUNET_SERVER_Handle *server, 921 struct GNUNET_SERVER_Handle *server,
898 const struct GNUNET_CONFIGURATION_Handle *cfg) 922 const struct GNUNET_CONFIGURATION_Handle *cfg)
899{ 923{
900 static const struct GNUNET_SERVER_MessageHandler handlers[] = { 924 static const struct GNUNET_SERVER_MessageHandler handlers[] = {
901 {&handle_set, NULL, GNUNET_MESSAGE_TYPE_MYNAME_SET, 0}, 925 {&handle_set, NULL, GNUNET_MESSAGE_TYPE_MYNAME_SET, 0},
902 {&handle_get, NULL, GNUNET_MESSAGE_TYPE_MYNAME_GET, 0}, 926 {&handle_get, NULL, GNUNET_MESSAGE_TYPE_MYNAME_GET, 0},
903 {NULL, NULL, 0, 0} 927 {NULL, NULL, 0, 0}
904 }; 928 };
905 GNUNET_SERVER_add_handlers (server, handlers); 929 GNUNET_SERVER_add_handlers (server, handlers);
906 /* do more setup work */ 930 /* do more setup work */
907} 931}
908\end{lstlisting} 932\end{lstlisting}
909 933
910Each handler function {\bf must} eventually (possibly in some 934Each handler function {\bf must} eventually (possibly in some
@@ -943,7 +967,7 @@ transmit_cb (void *cls, size_t size, void *buf)
943 return msg_size; 967 return msg_size;
944} 968}
945 969
946// ... 970// ...
947struct GNUNET_SERVER_TransmitHandle *th; 971struct GNUNET_SERVER_TransmitHandle *th;
948th = GNUNET_SERVER_notify_transmit_ready (client, 972th = GNUNET_SERVER_notify_transmit_ready (client,
949 msg_size, 973 msg_size,
@@ -955,7 +979,7 @@ th = GNUNET_SERVER_notify_transmit_ready (client,
955Only a single transmission request can be queued per client 979Only a single transmission request can be queued per client
956at the same time using this API. 980at the same time using this API.
957Additional APIs for sending messages to clients can be found 981Additional APIs for sending messages to clients can be found
958in the {\tt gnunet\_server\_lib.h} header. 982in the {\tt gnunet\_server\_lib.h} header.
959 983
960 984
961\exercise{Change the service respond to the request from your 985\exercise{Change the service respond to the request from your
@@ -964,7 +988,7 @@ client. Make sure you handle malformed messages in both directions.}
964 988
965\section{Interacting directly with other Peers using the CORE Service} 989\section{Interacting directly with other Peers using the CORE Service}
966 990
967One of the most important services in GNUnet is the \texttt{CORE} service 991One of the most important services in GNUnet is the \texttt{CORE} service
968managing connections between peers and handling encryption between peers. 992managing connections between peers and handling encryption between peers.
969 993
970One of the first things any service that extends the P2P protocol typically does 994One of the first things any service that extends the P2P protocol typically does
@@ -1043,14 +1067,14 @@ the two peers are connected? Why?}
1043 1067
1044\subsection{Sending P2P Messages} 1068\subsection{Sending P2P Messages}
1045 1069
1046In response to events (connect, disconnect, inbound messages, 1070In response to events (connect, disconnect, inbound messages,
1047timing, etc.) services can then use this API to transmit messages: 1071timing, etc.) services can then use this API to transmit messages:
1048 1072
1049\lstset{language=C} 1073\lstset{language=C}
1050\begin{lstlisting} 1074\begin{lstlisting}
1051typedef size_t 1075typedef size_t
1052(*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, 1076(*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls,
1053 size_t size, 1077 size_t size,
1054 void *buf) 1078 void *buf)
1055{ 1079{
1056 /* Fill "*buf" with up to "size" bytes, must start with GNUNET_MessageHeader */ 1080 /* Fill "*buf" with up to "size" bytes, must start with GNUNET_MessageHeader */
@@ -1133,7 +1157,7 @@ message_sent_cont (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
1133} 1157}
1134 1158
1135struct GNUNET_DHT_PutHandle * 1159struct GNUNET_DHT_PutHandle *
1136GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle, 1160GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle,
1137 const struct GNUNET_HashCode * key, 1161 const struct GNUNET_HashCode * key,
1138 uint32_t desired_replication_level, 1162 uint32_t desired_replication_level,
1139 enum GNUNET_DHT_RouteOption options, /* Route options, see next call */ 1163 enum GNUNET_DHT_RouteOption options, /* Route options, see next call */
@@ -1190,7 +1214,7 @@ get_handle =
1190 cls) 1214 cls)
1191\end{lstlisting} 1215\end{lstlisting}
1192 1216
1193\exercise{Store a value in the DHT and after a while retrieve it. Show the IDs of all 1217\exercise{Store a value in the DHT and after a while retrieve it. Show the IDs of all
1194the peers the requests have gone through. In order to convert a peer ID to a string, use 1218the peers the requests have gone through. In order to convert a peer ID to a string, use
1195the function GNUNET\_i2s. Pay attention to the route option parameters in both calls!} 1219the function GNUNET\_i2s. Pay attention to the route option parameters in both calls!}
1196 1220
@@ -1235,8 +1259,8 @@ block_plugin_SERVICE_evaluate (void *cls,
1235} 1259}
1236\end{lstlisting} 1260\end{lstlisting}
1237 1261
1238Note that it is mandatory to detect duplicate replies in this 1262Note that it is mandatory to detect duplicate replies in this
1239function and return the respective status code. Duplicate 1263function and return the respective status code. Duplicate
1240detection should be done by setting the respective bits in 1264detection should be done by setting the respective bits in
1241the Bloom filter {\tt bf}. Failure to do so may cause replies 1265the Bloom filter {\tt bf}. Failure to do so may cause replies
1242to circle in the network. 1266to circle in the network.
@@ -1291,7 +1315,7 @@ libgnunet_plugin_block_SERVICE_init (void *cls)
1291 1315
1292\subsubsection{Shutdown of the plugin} 1316\subsubsection{Shutdown of the plugin}
1293 1317
1294Following GNUnet's general plugin API concept, the plugin must 1318Following GNUnet's general plugin API concept, the plugin must
1295export a second function for cleaning up. It usually does very 1319export a second function for cleaning up. It usually does very
1296little. 1320little.
1297 1321
@@ -1316,7 +1340,7 @@ service \texttt{SERVICE} should contain a rule similar to this:
1316\lstset{language=make} 1340\lstset{language=make}
1317\begin{lstlisting} 1341\begin{lstlisting}
1318 plugindir = $(libdir)/gnunet 1342 plugindir = $(libdir)/gnunet
1319 1343
1320 plugin_LTLIBRARIES = \ 1344 plugin_LTLIBRARIES = \
1321 libgnunet_plugin_block_ext.la 1345 libgnunet_plugin_block_ext.la
1322 libgnunet_plugin_block_ext_la_SOURCES = \ 1346 libgnunet_plugin_block_ext_la_SOURCES = \
@@ -1405,7 +1429,7 @@ monitor_handle = GNUNET_DHT_monitor_start (dht_handle,
1405 1429
1406\section{Debugging with {\tt gnunet-arm}} 1430\section{Debugging with {\tt gnunet-arm}}
1407 1431
1408Even if services are managed by {\tt gnunet-arm}, you can start them with 1432Even if services are managed by {\tt gnunet-arm}, you can start them with
1409{\tt gdb} or {\tt valgrind}. For example, you could add the following lines 1433{\tt gdb} or {\tt valgrind}. For example, you could add the following lines
1410to your configuration file to start the DHT service in a {\tt gdb} session in a 1434to your configuration file to start the DHT service in a {\tt gdb} session in a
1411fresh {\tt xterm}: 1435fresh {\tt xterm}:
@@ -1420,19 +1444,19 @@ Alternatively, you can stop a service that was started via ARM and run it manual
1420\lstset{language=bash} 1444\lstset{language=bash}
1421\begin{lstlisting} 1445\begin{lstlisting}
1422$ gnunet-arm -k dht 1446$ gnunet-arm -k dht
1423$ gdb --args gnunet-service-dht -L DEBUG 1447$ gdb --args gnunet-service-dht -L DEBUG
1424$ valgrind gnunet-service-dht -L DEBUG 1448$ valgrind gnunet-service-dht -L DEBUG
1425\end{lstlisting} 1449\end{lstlisting}
1426% $ 1450% $
1427 1451
1428Assuming other services are well-written, they will automatically re-integrate the 1452Assuming other services are well-written, they will automatically re-integrate the
1429restarted service with the peer. 1453restarted service with the peer.
1430 1454
1431GNUnet provides a powerful logging mechanism providing log levels \texttt{ERROR}, 1455GNUnet provides a powerful logging mechanism providing log levels \texttt{ERROR},
1432\texttt{WARNING}, \texttt{INFO} and \texttt{DEBUG}. The current log level is 1456\texttt{WARNING}, \texttt{INFO} and \texttt{DEBUG}. The current log level is
1433configured using the \lstinline|$GNUNET_FORCE_LOG| environmental variable. 1457configured using the \lstinline|$GNUNET_FORCE_LOG| environmental variable.
1434The \texttt{DEBUG} level is only available if \lstinline|--enable-logging=verbose| was used when 1458The \texttt{DEBUG} level is only available if \lstinline|--enable-logging=verbose| was used when
1435running \texttt{configure}. More details about logging can be found under 1459running \texttt{configure}. More details about logging can be found under
1436\url{https://gnunet.org/logging}. 1460\url{https://gnunet.org/logging}.
1437 1461
1438You should also probably enable the creation of core files, by setting 1462You should also probably enable the creation of core files, by setting