\subsection{Start a peer}
Each GNUnet instance (called peer) has an identity (\textit{peer ID}) based on a
cryptographic public private key pair. The peer ID is the printable hash of the
-public key. So before starting the peer, you may want to just generate the peer's private
-key using the command
+public key.
+
+GNUnet services are controlled by a master service the so called \textit{Automatic Restart Manager} (ARM).
+ARM starts, stops and even restarts services automatically or on demand when a client connects.
+You interact with the ARM service using the \lstinline|gnunet-arm| tool.
+GNUnet can then be started with \lstinline|gnunet-arm -s| and stopped with
+\lstinline|gnunet-arm -e|. An additional service not automatically started
+can be started using \lstinline|gnunet-arm -i <service name>| and stopped
+using \lstinline|gnunet-arm -k <servicename>|.
+
+Once you have started your peer, you can use many other GNUnet commands
+to interact with it. For example, you can run:
\lstset{language=bash}
\begin{lstlisting}
-$ gnunet-peerinfo -c ~/peer1.conf -s
+$ gnunet-peerinfo -s
\end{lstlisting}
+to obtain the public key of your peer.
You should see an output containing the peer ID similar to:
\lstset{language=bash}
\begin{lstlisting}
I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
\end{lstlisting}
-GNUnet services are controlled by a master service the so called \textit{Automatic Restart Manager} (ARM).
-ARM starts, stops and even restarts services automatically or on demand when a client connects.
-You interact with the ARM service using the \lstinline|gnunet-arm| tool.
-GNUnet can then be started with \lstinline|gnunet-arm -s| and stopped with
-\lstinline|gnunet-arm -e|. An additional service not automatically started
-can be started using \lstinline|gnunet-arm -i <service name>| and stopped
-using \lstinline|gnunet-arm -k <servicename>|.
\subsection{Monitor a peer}
In this section, we will monitor the behaviour of our peer's DHT service with respect to a
If you want to use the \texttt{peerinfo} tool to connect your peers, you should:
\begin{itemize}
\itemsep0em
- \item{Remove {\tt hostlist} from {\tt DEFAULTSERVICES} (to not connect to the global GNUnet)}
+ \item{Set {\tt FORCESTART = NO} in section {\tt hostlist} (to not connect to the global GNUnet)}
\item{Start both peers running {\tt gnunet-arm -c peer1.conf -s} and {\tt gnunet-arm -c peer2.conf -s}}
\item{Get \texttt{HELLO} message of the first peer running {\tt gnunet-peerinfo -c peer1.conf -g}}
\item{Give the output to the second peer by running {\tt gnunet-peerinfo -c peer2.conf -p '<output>'}}
\exercise{Change the service respond to the request from your
client. Make sure you handle malformed messages in both directions.}
-
\section{Interacting directly with other Peers using the CORE Service}
One of the most important services in GNUnet is the \texttt{CORE} service
\exercise{Fix your service to handle peer disconnects.}
+\section{Storing peer-specific data using the PEERSTORE service}
+
+GNUnet's PEERSTORE service offers a persistorage for arbitrary peer-specific data.
+Other GNUnet services can use the PEERSTORE to store, retrieve and monitor data records.
+Each data record stored with PEERSTORE contains the following fields:
+
+\begin{itemize}
+\itemsep0em
+ \item subsystem: Name of the subsystem responsible for the record.
+ \item peerid: Identity of the peer this record is related to.
+ \item key: a key string identifying the record.
+ \item value: binary record value.
+ \item expiry: record expiry date.
+\end{itemize}
+
+The first step is to start a connection to the PEERSTORE service:
+\begin{lstlisting}
+#include "gnunet_peerstore_service.h"
+
+peerstore_handle = GNUNET_PEERSTORE_connect (cfg);
+\end{lstlisting}
+The service handle \lstinline|peerstore_handle| will be needed for all subsequent
+PEERSTORE operations.
+
+\subsection{Storing records}
+
+To store a new record, use the following function:
+\begin{lstlisting}
+struct GNUNET_PEERSTORE_StoreContext *
+GNUNET_PEERSTORE_store (struct GNUNET_PEERSTORE_Handle *h,
+ const char *sub_system,
+ const struct GNUNET_PeerIdentity *peer,
+ const char *key,
+ const void *value,
+ size_t size,
+ struct GNUNET_TIME_Absolute expiry,
+ enum GNUNET_PEERSTORE_StoreOption options,
+ GNUNET_PEERSTORE_Continuation cont,
+ void *cont_cls);
+\end{lstlisting}
+
+The \lstinline|options| parameter can either be \lstinline|GNUNET_PEERSTORE_STOREOPTION_MULTIPLE|
+which means that multiple values can be stored under the same key combination (subsystem, peerid, key),
+or \lstinline|GNUNET_PEERSTORE_STOREOPTION_REPLACE| which means that PEERSTORE will replace any
+existing values under the given key combination (subsystem, peerid, key) with the new given value.
+
+The continuation function \lstinline|cont| will be called after the store request is successfully
+sent to the PEERSTORE service. This does not guarantee that the record is successfully stored, only
+that it was received by the service.
+
+The \lstinline|GNUNET_PEERSTORE_store| function returns a handle to the store operation. This handle
+can be used to cancel the store operation only before the continuation function is called:
+\begin{lstlisting}
+void
+GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
+\end{lstlisting}
+
+\subsection{Retrieving records}
+
+To retrieve stored records, use the following function:
+\begin{lstlisting}
+struct GNUNET_PEERSTORE_IterateContext *
+GNUNET_PEERSTORE_iterate (struct GNUNET_PEERSTORE_Handle *h,
+ const char *sub_system,
+ const struct GNUNET_PeerIdentity *peer,
+ const char *key,
+ struct GNUNET_TIME_Relative timeout,
+ GNUNET_PEERSTORE_Processor callback,
+ void *callback_cls);
+\end{lstlisting}
+The values of \lstinline|peer| and \lstinline|key| can be \lstinline|NULL|. This allows the
+iteration over values stored under any of the following key combinations:
+\begin{itemize}
+\itemsep0em
+ \item (subsystem)
+ \item (subsystem, peerid)
+ \item (subsystem, key)
+ \item (subsystem, peerid, key)
+\end{itemize}
+
+The \lstinline|callback| function will be called once with each retrieved record and once
+more with a \lstinline|NULL| record to signal the end of results.
+
+The \lstinline|GNUNET_PEERSTORE_iterate| function returns a handle to the iterate operation. This
+handle can be used to cancel the iterate operation only before the callback function is called with
+a \lstinline|NULL| record.
+
+\subsection{Monitoring records}
+
+PEERSTORE offers the functionality of monitoring for new records stored under a specific key
+combination (subsystem, peerid, key). To start the monitoring, use the following function:
+\begin{lstlisting}
+struct GNUNET_PEERSTORE_WatchContext *
+GNUNET_PEERSTORE_watch (struct GNUNET_PEERSTORE_Handle *h,
+ const char *sub_system,
+ const struct GNUNET_PeerIdentity *peer,
+ const char *key,
+ GNUNET_PEERSTORE_Processor callback,
+ void *callback_cls);
+\end{lstlisting}
+
+Whenever a new record is stored under the given key combination, the \lstinline|callback| function
+will be called with this new record. This will continue until the connection to the PEERSTORE service
+is broken or the watch operation is canceled:
+\begin{lstlisting}
+void
+GNUNET_PEERSTORE_watch_cancel (struct GNUNET_PEERSTORE_WatchContext *wc);
+\end{lstlisting}
+
+\subsection{Disconnecting from PEERSTORE}
+
+When the connection to the PEERSTORE service is no longer needed, disconnect using the following
+function:
+\begin{lstlisting}
+void
+GNUNET_PEERSTORE_disconnect (struct GNUNET_PEERSTORE_Handle *h, int sync_first);
+\end{lstlisting}
+
+If the \lstinline|sync_first| flag is set to \lstinline|GNUNET_YES|, the API will delay the
+disconnection until all store requests are received by the PEERSTORE service. Otherwise,
+it will disconnect immediately.
+
\section{Using the DHT}
The DHT allows to store data so other peers in the P2P network can
access it and retrieve data stored by any peers in the network.
projects / oweals / gnunet.git / blobdiff