1 @c ***********************************************************************
2 @node GNUnet Developer Handbook
3 @chapter GNUnet Developer Handbook
5 This book is intended to be an introduction for programmers that want to
6 extend the GNUnet framework. GNUnet is more than a simple peer-to-peer
9 For developers, GNUnet is:
12 @item developed by a community that believes in the GNU philosophy
13 @item Free Software (Free as in Freedom), licensed under the
14 GNU Affero General Public License
15 (@uref{https://www.gnu.org/licenses/licenses.html#AGPL})
16 @item A set of standards, including coding conventions and
18 @item A set of layered protocols, both specifying the communication
19 between peers as well as the communication between components
21 @item A set of libraries with well-defined APIs suitable for
25 In particular, the architecture specifies that a peer consists of many
26 processes communicating via protocols. Processes can be written in almost
28 @code{C}, @code{Java} and @code{Guile} APIs exist for accessing existing
29 services and for writing extensions.
30 It is possible to write extensions in other languages by
31 implementing the necessary IPC protocols.
33 GNUnet can be extended and improved along many possible dimensions, and
34 anyone interested in Free Software and Freedom-enhancing Networking is
35 welcome to join the effort. This Developer Handbook attempts to provide
36 an initial introduction to some of the key design choices and central
37 components of the system.
38 This part of the GNUNet documentation is far from complete,
39 and we welcome informed contributions, be it in the form of
40 new chapters, sections or insightful comments.
43 * Developer Introduction::
44 * Internal dependencies::
46 * System Architecture::
47 * Subsystem stability::
48 * Naming conventions and coding style guide::
50 * Developing extensions for GNUnet using the gnunet-ext template::
52 * Building GNUnet and its dependencies::
54 * Performance regression analysis with Gauger::
57 * Automatic Restart Manager (ARM)::
58 * TRANSPORT Subsystem::
60 * Distance-Vector plugin::
68 * HOSTLIST Subsystem::
69 * IDENTITY Subsystem::
70 * NAMESTORE Subsystem::
71 * PEERINFO Subsystem::
72 * PEERSTORE Subsystem::
74 * STATISTICS Subsystem::
75 * Distributed Hash Table (DHT)::
76 * GNU Name System (GNS)::
78 * REVOCATION Subsystem::
79 * File-sharing (FS) Subsystem::
84 @node Developer Introduction
85 @section Developer Introduction
87 This Developer Handbook is intended as first introduction to GNUnet for
88 new developers that want to extend the GNUnet framework. After the
89 introduction, each of the GNUnet subsystems (directories in the
90 @file{src/} tree) is (supposed to be) covered in its own chapter. In
91 addition to this documentation, GNUnet developers should be aware of the
92 services available on the GNUnet server to them.
94 New developers can have a look a the GNUnet tutorials for C and java
95 available in the @file{src/} directory of the repository or under the
98 @c ** FIXME: Link to files in source, not online.
99 @c ** FIXME: Where is the Java tutorial?
101 @item @xref{Top, Introduction,, gnunet-c-tutorial, The GNUnet C Tutorial}.
103 @c @item @uref{https://gnunet.org/git/gnunet.git/plain/doc/gnunet-c-tutorial.pdf, GNUnet C tutorial}
104 @item GNUnet Java tutorial
107 In addition to the GNUnet Reference Documentation you are reading,
108 the GNUnet server at @uref{https://gnunet.org} contains
109 various resources for GNUnet developers and those
110 who aspire to become regular contributors.
111 They are all conveniently reachable via the "Developer"
112 entry in the navigation menu. Some additional tools (such as static
113 analysis reports) require a special developer access to perform certain
114 operations. If you want (or require) access, you should contact
115 @uref{http://grothoff.org/christian/, Christian Grothoff},
118 @c FIXME: A good part of this belongs on the website or should be
119 @c extended in subsections explaining usage of this. A simple list
120 @c is just taking space people have to read.
121 The public subsystems on the GNUnet server that help developers are:
125 @item The version control system (git) keeps our code and enables
126 distributed development.
127 It is publicly accessible at @uref{https://gnunet.org/git/}.
128 Only developers with write access can commit code, everyone else is
129 encouraged to submit patches to the GNUnet-developers mailinglist:
130 @uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, https://lists.gnu.org/mailman/listinfo/gnunet-developers}
132 @item The bugtracking system (Mantis).
133 We use it to track feature requests, open bug reports and their
135 It can be accessed at
136 @uref{https://gnunet.org/bugs/, https://gnunet.org/bugs/}.
137 Anyone can report bugs.
139 @item Our site installation of the
140 Continuous Integration (CI) system @code{Buildbot} is used
141 to check GNUnet builds automatically on a range of platforms.
142 The web interface of this CI is exposed at
143 @uref{https://gnunet.org/buildbot/, https://gnunet.org/buildbot/}.
144 Builds are triggered automatically 30 minutes after the last commit to
145 our repository was made.
147 @item The current quality of our automated test suite is assessed using
148 Code coverage analysis. This analysis is run daily; however the webpage
149 is only updated if all automated tests pass at that time. Testcases that
150 improve our code coverage are always welcome.
152 @item We try to automatically find bugs using a static analysis scan.
153 This scan is run daily; however the webpage is only updated if all
154 automated tests pass at the time. Note that not everything that is
155 flagged by the analysis is a bug, sometimes even good code can be marked
156 as possibly problematic. Nevertheless, developers are encouraged to at
157 least be aware of all issues in their code that are listed.
159 @item We use Gauger for automatic performance regression visualization.
161 Details on how to use Gauger are here.
163 @item We use @uref{http://junit.org/, junit} to automatically test
164 @command{gnunet-java}.
165 Automatically generated, current reports on the test suite are here.
168 @item We use Cobertura to generate test coverage reports for gnunet-java.
169 Current reports on test coverage are here.
176 @c ***********************************************************************
181 @node Project overview
182 @subsection Project overview
184 The GNUnet project consists at this point of several sub-projects. This
185 section is supposed to give an initial overview about the various
186 sub-projects. Note that this description also lists projects that are far
187 from complete, including even those that have literally not a single line
190 GNUnet sub-projects in order of likely relevance are currently:
194 @item @command{gnunet}
195 Core of the P2P framework, including file-sharing, VPN and
196 chat applications; this is what the Developer Handbook covers mostly
197 @item @command{gnunet-gtk}
198 Gtk+-based user interfaces, including:
201 @item @command{gnunet-fs-gtk} (file-sharing),
202 @item @command{gnunet-statistics-gtk} (statistics over time),
203 @item @command{gnunet-peerinfo-gtk}
204 (information about current connections and known peers),
205 @item @command{gnunet-chat-gtk} (chat GUI) and
206 @item @command{gnunet-setup} (setup tool for "everything")
209 @item @command{gnunet-fuse}
210 Mounting directories shared via GNUnet's file-sharing
211 on GNU/Linux distributions
212 @item @command{gnunet-update}
213 Installation and update tool
214 @item @command{gnunet-ext}
215 Template for starting 'external' GNUnet projects
216 @item @command{gnunet-java}
217 Java APIs for writing GNUnet services and applications
218 @item @command{gnunet-java-ext}
219 @item @command{eclectic}
220 Code to run GNUnet nodes on testbeds for research, development,
221 testing and evaluation
222 @c ** FIXME: Solve the status and location of gnunet-qt
223 @item @command{gnunet-qt}
224 Qt-based GNUnet GUI (is it deprecated?)
225 @item @command{gnunet-cocoa}
226 cocoa-based GNUnet GUI (is it deprecated?)
227 @item @command{gnunet-guile}
228 Guile bindings for GNUnet
229 @item @command{gnunet-python}
230 Python bindings for GNUnet
234 We are also working on various supporting libraries and tools:
235 @c ** FIXME: What about gauger, and what about libmwmodem?
238 @item @command{libextractor}
239 GNU libextractor (meta data extraction)
240 @item @command{libmicrohttpd}
241 GNU libmicrohttpd (embedded HTTP(S) server library)
242 @item @command{gauger}
243 Tool for performance regression analysis
244 @item @command{monkey}
245 Tool for automated debugging of distributed systems
246 @item @command{libmwmodem}
247 Library for accessing satellite connection quality reports
248 @item @command{libgnurl}
249 gnURL (feature-restricted variant of cURL/libcurl)
251 work in progress of the new gnunet.org website (Jinja2 framework based to
252 replace our current Drupal website)
253 @item @command{bibliography}
254 Our collected bibliography, papers, references, and so forth
255 @item @command{gnunet-videos-}
256 Videos about and around gnunet activities
259 Finally, there are various external projects (see links for a list of
260 those that have a public website) which build on top of the GNUnet
263 @c ***********************************************************************
264 @node Internal dependencies
265 @section Internal dependencies
267 This section tries to give an overview of what processes a typical GNUnet
268 peer running a particular application would consist of. All of the
269 processes listed here should be automatically started by
270 @command{gnunet-arm -s}.
271 The list is given as a rough first guide to users for failure diagnostics.
272 Ideally, end-users should never have to worry about these internal
275 In terms of internal dependencies, a minimum file-sharing system consists
276 of the following GNUnet processes (in order of dependency):
279 @item gnunet-service-arm
280 @item gnunet-service-resolver (required by all)
281 @item gnunet-service-statistics (required by all)
282 @item gnunet-service-peerinfo
283 @item gnunet-service-transport (requires peerinfo)
284 @item gnunet-service-core (requires transport)
285 @item gnunet-daemon-hostlist (requires core)
286 @item gnunet-daemon-topology (requires hostlist, peerinfo)
287 @item gnunet-service-datastore
288 @item gnunet-service-dht (requires core)
289 @item gnunet-service-identity
290 @item gnunet-service-fs (requires identity, mesh, dht, datastore, core)
294 A minimum VPN system consists of the following GNUnet processes (in
295 order of dependency):
298 @item gnunet-service-arm
299 @item gnunet-service-resolver (required by all)
300 @item gnunet-service-statistics (required by all)
301 @item gnunet-service-peerinfo
302 @item gnunet-service-transport (requires peerinfo)
303 @item gnunet-service-core (requires transport)
304 @item gnunet-daemon-hostlist (requires core)
305 @item gnunet-service-dht (requires core)
306 @item gnunet-service-mesh (requires dht, core)
307 @item gnunet-service-dns (requires dht)
308 @item gnunet-service-regex (requires dht)
309 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
313 A minimum GNS system consists of the following GNUnet processes (in
314 order of dependency):
317 @item gnunet-service-arm
318 @item gnunet-service-resolver (required by all)
319 @item gnunet-service-statistics (required by all)
320 @item gnunet-service-peerinfo
321 @item gnunet-service-transport (requires peerinfo)
322 @item gnunet-service-core (requires transport)
323 @item gnunet-daemon-hostlist (requires core)
324 @item gnunet-service-dht (requires core)
325 @item gnunet-service-mesh (requires dht, core)
326 @item gnunet-service-dns (requires dht)
327 @item gnunet-service-regex (requires dht)
328 @item gnunet-service-vpn (requires regex, dns, mesh, dht)
329 @item gnunet-service-identity
330 @item gnunet-service-namestore (requires identity)
331 @item gnunet-service-gns (requires vpn, dns, dht, namestore, identity)
334 @c ***********************************************************************
336 @section Code overview
338 This section gives a brief overview of the GNUnet source code.
339 Specifically, we sketch the function of each of the subdirectories in
340 the @file{gnunet/src/} directory. The order given is roughly bottom-up
341 (in terms of the layers of the system).
344 @item @file{util/} --- libgnunetutil
345 Library with general utility functions, all
346 GNUnet binaries link against this library. Anything from memory
347 allocation and data structures to cryptography and inter-process
348 communication. The goal is to provide an OS-independent interface and
349 more 'secure' or convenient implementations of commonly used primitives.
350 The API is spread over more than a dozen headers, developers should study
351 those closely to avoid duplicating existing functions.
352 @pxref{libgnunetutil}.
353 @item @file{hello/} --- libgnunethello
354 HELLO messages are used to
355 describe under which addresses a peer can be reached (for example,
356 protocol, IP, port). This library manages parsing and generating of HELLO
358 @item @file{block/} --- libgnunetblock
359 The DHT and other components of GNUnet
360 store information in units called 'blocks'. Each block has a type and the
361 type defines a particular format and how that binary format is to be
362 linked to a hash code (the key for the DHT and for databases). The block
363 library is a wrapper around block plugins which provide the necessary
364 functions for each block type.
365 @item @file{statistics/} --- statistics service
366 The statistics service enables associating
367 values (of type uint64_t) with a component name and a string. The main
368 uses is debugging (counting events), performance tracking and user
369 entertainment (what did my peer do today?).
370 @item @file{arm/} --- Automatic Restart Manager (ARM)
371 The automatic-restart-manager (ARM) service
372 is the GNUnet master service. Its role is to start gnunet-services, to
373 re-start them when they crashed and finally to shut down the system when
375 @item @file{peerinfo/} --- peerinfo service
376 The peerinfo service keeps track of which peers are known
377 to the local peer and also tracks the validated addresses for each peer
378 (in the form of a HELLO message) for each of those peers. The peer is not
379 necessarily connected to all peers known to the peerinfo service.
380 Peerinfo provides persistent storage for peer identities --- peers are
381 not forgotten just because of a system restart.
382 @item @file{datacache/} --- libgnunetdatacache
383 The datacache library provides (temporary) block storage for the DHT.
384 Existing plugins can store blocks in Sqlite, Postgres or MySQL databases.
385 All data stored in the cache is lost when the peer is stopped or
386 restarted (datacache uses temporary tables).
387 @item @file{datastore/} --- datastore service
388 The datastore service stores file-sharing blocks in
389 databases for extended periods of time. In contrast to the datacache, data
390 is not lost when peers restart. However, quota restrictions may still
391 cause old, expired or low-priority data to be eventually discarded.
392 Existing plugins can store blocks in Sqlite, Postgres or MySQL databases.
393 @item @file{template/} --- service template
394 Template for writing a new service. Does nothing.
395 @item @file{ats/} --- Automatic Transport Selection
396 The automatic transport selection (ATS) service
397 is responsible for deciding which address (i.e.
398 which transport plugin) should be used for communication with other peers,
399 and at what bandwidth.
400 @item @file{nat/} --- libgnunetnat
401 Library that provides basic functions for NAT traversal.
402 The library supports NAT traversal with
403 manual hole-punching by the user, UPnP and ICMP-based autonomous NAT
404 traversal. The library also includes an API for testing if the current
405 configuration works and the @code{gnunet-nat-server} which provides an
406 external service to test the local configuration.
407 @item @file{fragmentation/} --- libgnunetfragmentation
408 Some transports (UDP and WLAN, mostly) have restrictions on the maximum
409 transfer unit (MTU) for packets. The fragmentation library can be used to
410 break larger packets into chunks of at most 1k and transmit the resulting
411 fragments reliably (with acknowledgment, retransmission, timeouts,
413 @item @file{transport/} --- transport service
414 The transport service is responsible for managing the
415 basic P2P communication. It uses plugins to support P2P communication
416 over TCP, UDP, HTTP, HTTPS and other protocols.The transport service
417 validates peer addresses, enforces bandwidth restrictions, limits the
418 total number of connections and enforces connectivity restrictions (i.e.
420 @item @file{peerinfo-tool/} --- gnunet-peerinfo
421 This directory contains the gnunet-peerinfo binary which can be used to
422 inspect the peers and HELLOs known to the peerinfo service.
424 The core service is responsible for establishing encrypted, authenticated
425 connections with other peers, encrypting and decrypting messages and
426 forwarding messages to higher-level services that are interested in them.
427 @item @file{testing/} --- libgnunettesting
428 The testing library allows starting (and stopping) peers
429 for writing testcases.
430 It also supports automatic generation of configurations for peers
431 ensuring that the ports and paths are disjoint. libgnunettesting is also
432 the foundation for the testbed service
433 @item @file{testbed/} --- testbed service
434 The testbed service is used for creating small or large scale deployments
435 of GNUnet peers for evaluation of protocols.
436 It facilitates peer deployments on multiple
437 hosts (for example, in a cluster) and establishing various network
438 topologies (both underlay and overlay).
439 @item @file{nse/} --- Network Size Estimation
440 The network size estimation (NSE) service
441 implements a protocol for (securely) estimating the current size of the
443 @item @file{dht/} --- distributed hash table
444 The distributed hash table (DHT) service provides a
445 distributed implementation of a hash table to store blocks under hash
446 keys in the P2P network.
447 @item @file{hostlist/} --- hostlist service
448 The hostlist service allows learning about
449 other peers in the network by downloading HELLO messages from an HTTP
450 server, can be configured to run such an HTTP server and also implements
451 a P2P protocol to advertise and automatically learn about other peers
452 that offer a public hostlist server.
453 @item @file{topology/} --- topology service
454 The topology service is responsible for
455 maintaining the mesh topology. It tries to maintain connections to friends
456 (depending on the configuration) and also tries to ensure that the peer
457 has a decent number of active connections at all times. If necessary, new
458 connections are added. All peers should run the topology service,
459 otherwise they may end up not being connected to any other peer (unless
460 some other service ensures that core establishes the required
461 connections). The topology service also tells the transport service which
462 connections are permitted (for friend-to-friend networking)
463 @item @file{fs/} --- file-sharing
464 The file-sharing (FS) service implements GNUnet's
465 file-sharing application. Both anonymous file-sharing (using gap) and
466 non-anonymous file-sharing (using dht) are supported.
467 @item @file{cadet/} --- cadet service
468 The CADET service provides a general-purpose routing abstraction to create
469 end-to-end encrypted tunnels in mesh networks. We wrote a paper
470 documenting key aspects of the design.
471 @item @file{tun/} --- libgnunettun
472 Library for building IPv4, IPv6 packets and creating
473 checksums for UDP, TCP and ICMP packets. The header
474 defines C structs for common Internet packet formats and in particular
475 structs for interacting with TUN (virtual network) interfaces.
476 @item @file{mysql/} --- libgnunetmysql
477 Library for creating and executing prepared MySQL
478 statements and to manage the connection to the MySQL database.
479 Essentially a lightweight wrapper for the interaction between GNUnet
480 components and libmysqlclient.
482 Service that allows intercepting and modifying DNS requests of
483 the local machine. Currently used for IPv4-IPv6 protocol translation
484 (DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The
485 service can also be configured to offer an exit service for DNS traffic.
486 @item @file{vpn/} --- VPN service
487 The virtual public network (VPN) service provides a virtual
488 tunnel interface (VTUN) for IP routing over GNUnet.
489 Needs some other peers to run an "exit" service to work.
490 Can be activated using the "gnunet-vpn" tool or integrated with DNS using
493 Daemon to allow traffic from the VPN to exit this
494 peer to the Internet or to specific IP-based services of the local peer.
495 Currently, an exit service can only be restricted to IPv4 or IPv6, not to
496 specific ports and or IP address ranges. If this is not acceptable,
497 additional firewall rules must be added manually. exit currently only
498 works for normal UDP, TCP and ICMP traffic; DNS queries need to leave the
499 system via a DNS service.
501 protocol translation daemon. This daemon enables 4-to-6,
502 6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It
503 essentially uses "DNS" to intercept DNS replies and then maps results to
504 those offered by the VPN, which then sends them using mesh to some daemon
505 offering an appropriate exit service.
506 @item @file{identity/}
507 Management of egos (alter egos) of a user; identities are
508 essentially named ECC private keys and used for zones in the GNU name
509 system and for namespaces in file-sharing, but might find other uses later
510 @item @file{revocation/}
511 Key revocation service, can be used to revoke the
512 private key of an identity if it has been compromised
513 @item @file{namecache/}
514 Cache for resolution results for the GNU name system;
515 data is encrypted and can be shared among users,
516 loss of the data should ideally only result in a
517 performance degradation (persistence not required)
518 @item @file{namestore/}
519 Database for the GNU name system with per-user private information,
522 GNU name system, a GNU approach to DNS and PKI.
524 A plugin for distance-vector (DV)-based routing.
525 DV consists of a service and a transport plugin to provide peers
526 with the illusion of a direct P2P connection for connections
527 that use multiple (typically up to 3) hops in the actual underlay network.
529 Service for the (distributed) evaluation of regular expressions.
530 @item @file{scalarproduct/}
531 The scalar product service offers an API to perform a secure multiparty
532 computation which calculates a scalar product between two peers
533 without exposing the private input vectors of the peers to each other.
534 @item @file{consensus/}
535 The consensus service will allow a set of peers to agree
536 on a set of values via a distributed set union computation.
538 The rest API allows access to GNUnet services using RESTful interaction.
539 The services provide plugins that can exposed by the rest server.
540 @c FIXME: Where did this disappear to?
541 @c @item @file{experimentation/}
542 @c The experimentation daemon coordinates distributed
543 @c experimentation to evaluate transport and ATS properties.
546 @c ***********************************************************************
547 @node System Architecture
548 @section System Architecture
550 @c FIXME: For those irritated by the textflow, we are missing images here,
551 @c in the short term we should add them back, in the long term this should
552 @c work without images or have images with alt-text.
554 GNUnet developers like LEGOs. The blocks are indestructible, can be
555 stacked together to construct complex buildings and it is generally easy
556 to swap one block for a different one that has the same shape. GNUnet's
557 architecture is based on LEGOs:
559 @c @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs as connectors upon Network Protocol on top of a Service}
561 This chapter documents the GNUnet LEGO system, also known as GNUnet's
564 The most common GNUnet component is a service. Services offer an API (or
565 several, depending on what you count as "an API") which is implemented as
566 a library. The library communicates with the main process of the service
567 using a service-specific network protocol. The main process of the service
568 typically doesn't fully provide everything that is needed --- it has holes
569 to be filled by APIs to other services.
571 A special kind of component in GNUnet are user interfaces and daemons.
572 Like services, they have holes to be filled by APIs of other services.
573 Unlike services, daemons do not implement their own network protocol and
576 The GNUnet system provides a range of services, daemons and user
577 interfaces, which are then combined into a layered GNUnet instance (also
580 Note that while it is generally possible to swap one service for another
581 compatible service, there is often only one implementation. However,
582 during development we often have a "new" version of a service in parallel
583 with an "old" version. While the "new" version is not working, developers
584 working on other parts of the service can continue their development by
585 simply using the "old" service. Alternative design ideas can also be
586 easily investigated by swapping out individual components. This is
587 typically achieved by simply changing the name of the "BINARY" in the
588 respective configuration section.
590 Key properties of GNUnet services are that they must be separate
591 processes and that they must protect themselves by applying tight error
592 checking against the network protocol they implement (thereby achieving a
593 certain degree of robustness).
595 On the other hand, the APIs are implemented to tolerate failures of the
596 service, isolating their host process from errors by the service. If the
597 service process crashes, other services and daemons around it should not
598 also fail, but instead wait for the service process to be restarted by
602 @c ***********************************************************************
603 @node Subsystem stability
604 @section Subsystem stability
606 This section documents the current stability of the various GNUnet
607 subsystems. Stability here describes the expected degree of compatibility
608 with future versions of GNUnet. For each subsystem we distinguish between
609 compatibility on the P2P network level (communication protocol between
610 peers), the IPC level (communication between the service and the service
611 library) and the API level (stability of the API). P2P compatibility is
612 relevant in terms of which applications are likely going to be able to
613 communicate with future versions of the network. IPC communication is
614 relevant for the implementation of language bindings that re-implement the
615 IPC messages. Finally, API compatibility is relevant to developers that
616 hope to be able to avoid changes to applications build on top of the APIs
619 The following table summarizes our current view of the stability of the
620 respective protocols or APIs:
622 @multitable @columnfractions .20 .20 .20 .20
623 @headitem Subsystem @tab P2P @tab IPC @tab C API
624 @item util @tab n/a @tab n/a @tab stable
625 @item arm @tab n/a @tab stable @tab stable
626 @item ats @tab n/a @tab unstable @tab testing
627 @item block @tab n/a @tab n/a @tab stable
628 @item cadet @tab testing @tab testing @tab testing
629 @item consensus @tab experimental @tab experimental @tab experimental
630 @item core @tab stable @tab stable @tab stable
631 @item datacache @tab n/a @tab n/a @tab stable
632 @item datastore @tab n/a @tab stable @tab stable
633 @item dht @tab stable @tab stable @tab stable
634 @item dns @tab stable @tab stable @tab stable
635 @item dv @tab testing @tab testing @tab n/a
636 @item exit @tab testing @tab n/a @tab n/a
637 @item fragmentation @tab stable @tab n/a @tab stable
638 @item fs @tab stable @tab stable @tab stable
639 @item gns @tab stable @tab stable @tab stable
640 @item hello @tab n/a @tab n/a @tab testing
641 @item hostlist @tab stable @tab stable @tab n/a
642 @item identity @tab stable @tab stable @tab n/a
643 @item multicast @tab experimental @tab experimental @tab experimental
644 @item mysql @tab stable @tab n/a @tab stable
645 @item namestore @tab n/a @tab stable @tab stable
646 @item nat @tab n/a @tab n/a @tab stable
647 @item nse @tab stable @tab stable @tab stable
648 @item peerinfo @tab n/a @tab stable @tab stable
649 @item psyc @tab experimental @tab experimental @tab experimental
650 @item pt @tab n/a @tab n/a @tab n/a
651 @item regex @tab stable @tab stable @tab stable
652 @item revocation @tab stable @tab stable @tab stable
653 @item social @tab experimental @tab experimental @tab experimental
654 @item statistics @tab n/a @tab stable @tab stable
655 @item testbed @tab n/a @tab testing @tab testing
656 @item testing @tab n/a @tab n/a @tab testing
657 @item topology @tab n/a @tab n/a @tab n/a
658 @item transport @tab stable @tab stable @tab stable
659 @item tun @tab n/a @tab n/a @tab stable
660 @item vpn @tab testing @tab n/a @tab n/a
663 Here is a rough explanation of the values:
667 No incompatible changes are planned at this time; for IPC/APIs, if
668 there are incompatible changes, they will be minor and might only require
669 minimal changes to existing code; for P2P, changes will be avoided if at
670 all possible for the 0.10.x-series
673 No incompatible changes are
674 planned at this time, but the code is still known to be in flux; so while
675 we have no concrete plans, our expectation is that there will still be
676 minor modifications; for P2P, changes will likely be extensions that
677 should not break existing code
680 Changes are planned and will happen; however, they
681 will not be totally radical and the result should still resemble what is
682 there now; nevertheless, anticipated changes will break protocol/API
686 Changes are planned and the result may look nothing like
687 what the API/protocol looks like today
690 Someone should think about where this subsystem headed
693 This subsystem does not have an API/IPC-protocol/P2P-protocol
696 @c ***********************************************************************
697 @node Naming conventions and coding style guide
698 @section Naming conventions and coding style guide
700 Here you can find some rules to help you write code for GNUnet.
702 @c ***********************************************************************
704 * Naming conventions::
708 @node Naming conventions
709 @subsection Naming conventions
712 @c ***********************************************************************
719 * private (library-internal) symbols (including structs and macros)::
721 * performance tests::
726 @subsubsection include files
729 @item _lib: library without need for a process
730 @item _service: library that needs a service process
731 @item _plugin: plugin definition
732 @item _protocol: structs used in network protocol
735 @item gnunet_config.h --- generated
736 @item platform.h --- first included
737 @item plibc.h --- external library
738 @item gnunet_common.h --- fundamental routines
739 @item gnunet_directories.h --- generated
740 @item gettext.h --- external library
744 @c ***********************************************************************
746 @subsubsection binaries
749 @item gnunet-service-xxx: service process (has listen socket)
750 @item gnunet-daemon-xxx: daemon process (no listen socket)
751 @item gnunet-helper-xxx[-yyy]: SUID helper for module xxx
752 @item gnunet-yyy: command-line tool for end-users
753 @item libgnunet_plugin_xxx_yyy.so: plugin for API xxx
754 @item libgnunetxxx.so: library for API xxx
757 @c ***********************************************************************
759 @subsubsection logging
762 @item services and daemons use their directory name in
763 @code{GNUNET_log_setup} (i.e. 'core') and log using
765 @item command-line tools use their full name in
766 @code{GNUNET_log_setup} (i.e. 'gnunet-publish') and log using
768 @item service access libraries log using
769 '@code{GNUNET_log_from}' and use '@code{DIRNAME-api}' for the
770 component (i.e. 'core-api')
771 @item pure libraries (without associated service) use
772 '@code{GNUNET_log_from}' with the component set to their
773 library name (without lib or '@file{.so}'),
774 which should also be their directory name (i.e. '@file{nat}')
775 @item plugins should use '@code{GNUNET_log_from}'
776 with the directory name and the plugin name combined to produce
777 the component name (i.e. 'transport-tcp').
778 @item logging should be unified per-file by defining a
779 @code{LOG} macro with the appropriate arguments,
783 #define LOG(kind,...)
784 GNUNET_log_from (kind, "example-api",__VA_ARGS__)
789 @c ***********************************************************************
791 @subsubsection configuration
794 @item paths (that are substituted in all filenames) are in PATHS
795 (have as few as possible)
796 @item all options for a particular module (@file{src/MODULE})
797 are under @code{[MODULE]}
798 @item options for a plugin of a module
799 are under @code{[MODULE-PLUGINNAME]}
802 @c ***********************************************************************
803 @node exported symbols
804 @subsubsection exported symbols
807 @item must start with @code{GNUNET_modulename_} and be defined in
809 @item exceptions: those defined in @file{gnunet_common.h}
812 @c ***********************************************************************
813 @node private (library-internal) symbols (including structs and macros)
814 @subsubsection private (library-internal) symbols (including structs and macros)
817 @item must NOT start with any prefix
818 @item must not be exported in a way that linkers could use them or@ other
819 libraries might see them via headers; they must be either
820 declared/defined in C source files or in headers that are in the
821 respective directory under @file{src/modulename/} and NEVER be declared
822 in @file{src/include/}.
826 @subsubsection testcases
829 @item must be called @file{test_module-under-test_case-description.c}
830 @item "case-description" maybe omitted if there is only one test
833 @c ***********************************************************************
834 @node performance tests
835 @subsubsection performance tests
838 @item must be called @file{perf_module-under-test_case-description.c}
839 @item "case-description" maybe omitted if there is only one performance
841 @item Must only be run if @code{HAVE_BENCHMARKS} is satisfied
844 @c ***********************************************************************
845 @node src/ directories
846 @subsubsection src/ directories
849 @item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm)
850 @item gnunet-service-NAME: service processes with accessor library (i.e.,
852 @item libgnunetNAME: accessor library (_service.h-header) or standalone
853 library (_lib.h-header)
854 @item gnunet-daemon-NAME: daemon process without accessor library (i.e.,
855 gnunet-daemon-hostlist) and no GNUnet management port
856 @item libgnunet_plugin_DIR_NAME: loadable plugins (i.e.,
857 libgnunet_plugin_transport_tcp)
862 @subsection Coding style
864 @c XXX: Adjust examples to GNU Standards!
866 @item We follow the GNU Coding Standards (@pxref{Top, The GNU Coding Standards,, standards, The GNU Coding Standards});
867 @item Indentation is done with spaces, two per level, no tabs;
868 @item C99 struct initialization is fine;
869 @item declare only one variable per line, for example:
886 @c TODO: include actual example from a file in source
889 This helps keep diffs small and forces developers to think precisely about
890 the type of every variable.
891 Note that @code{char *} is different from @code{const char*} and
892 @code{int} is different from @code{unsigned int} or @code{uint32_t}.
893 Each variable type should be chosen with care.
895 @item While @code{goto} should generally be avoided, having a
896 @code{goto} to the end of a function to a block of clean up
897 statements (free, close, etc.) can be acceptable.
899 @item Conditions should be written with constants on the left (to avoid
900 accidental assignment) and with the @code{true} target being either the
901 @code{error} case or the significantly simpler continuation. For example:
904 if (0 != stat ("filename," &sbuf)) @{
908 /* handle normal case here */
916 if (stat ("filename," &sbuf) == 0) @{
917 /* handle normal case here */
924 If possible, the error clause should be terminated with a @code{return} (or
925 @code{goto} to some cleanup routine) and in this case, the @code{else} clause
929 if (0 != stat ("filename," &sbuf)) @{
933 /* handle normal case here */
936 This serves to avoid deep nesting. The 'constants on the left' rule
937 applies to all constants (including. @code{GNUNET_SCHEDULER_NO_TASK}),
938 NULL, and enums). With the two above rules (constants on left, errors in
939 'true' branch), there is only one way to write most branches correctly.
941 @item Combined assignments and tests are allowed if they do not hinder
942 code clarity. For example, one can write:
945 if (NULL == (value = lookup_function())) @{
951 @item Use @code{break} and @code{continue} wherever possible to avoid
952 deep(er) nesting. Thus, we would write:
956 while (NULL != (pos = next)) @{
958 if (! should_free (pos))
960 GNUNET_CONTAINER_DLL_remove (head, tail, pos);
968 next = head; while (NULL != (pos = next)) @{
970 if (should_free (pos)) @{
971 /* unnecessary nesting! */
972 GNUNET_CONTAINER_DLL_remove (head, tail, pos);
978 @item We primarily use @code{for} and @code{while} loops.
979 A @code{while} loop is used if the method for advancing in the loop is
980 not a straightforward increment operation. In particular, we use:
984 while (NULL != (pos = next))
987 if (! should_free (pos))
989 GNUNET_CONTAINER_DLL_remove (head, tail, pos);
994 to free entries in a list (as the iteration changes the structure of the
995 list due to the free; the equivalent @code{for} loop does no longer
996 follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}).
997 However, for loops that do follow the simple @code{for} paradigm we do
998 use @code{for}, even if it involves linked lists:
1001 /* simple iteration over a linked list */
1011 @item The first argument to all higher-order functions in GNUnet must be
1012 declared to be of type @code{void *} and is reserved for a closure. We do
1013 not use inner functions, as trampolines would conflict with setups that
1014 use non-executable stacks.
1015 The first statement in a higher-order function, which unusually should
1016 be part of the variable declarations, should assign the
1017 @code{cls} argument to the precise expected type. For example:
1020 int callback (void *cls, char *args) @{
1021 struct Foo *foo = cls;
1022 int other_variables;
1024 /* rest of function */
1029 @item It is good practice to write complex @code{if} expressions instead
1030 of using deeply nested @code{if} statements. However, except for addition
1031 and multiplication, all operators should use parens. This is fine:
1034 if ( (1 == foo) || ((0 == bar) && (x != y)) )
1039 However, this is not:
1044 if (0 == bar && x != y)
1049 Note that splitting the @code{if} statement above is debatable as the
1050 @code{return x} is a very trivial statement. However, once the logic after
1051 the branch becomes more complicated (and is still identical), the "or"
1052 formulation should be used for sure.
1054 @item There should be two empty lines between the end of the function and
1055 the comments describing the following function. There should be a single
1056 empty line after the initial variable declarations of a function. If a
1057 function has no local variables, there should be no initial empty line. If
1058 a long function consists of several complex steps, those steps might be
1059 separated by an empty line (possibly followed by a comment describing the
1060 following step). The code should not contain empty lines in arbitrary
1061 places; if in doubt, it is likely better to NOT have an empty line (this
1062 way, more code will fit on the screen).
1065 @c ***********************************************************************
1067 @section Build-system
1069 If you have code that is likely not to compile or build rules you might
1070 want to not trigger for most developers, use @code{if HAVE_EXPERIMENTAL}
1071 in your @file{Makefile.am}.
1072 Then it is OK to (temporarily) add non-compiling (or known-to-not-port)
1075 If you want to compile all testcases but NOT run them, run configure with
1076 the @code{--enable-test-suppression} option.
1078 If you want to run all testcases, including those that take a while, run
1079 configure with the @code{--enable-expensive-testcases} option.
1081 If you want to compile and run benchmarks, run configure with the
1082 @code{--enable-benchmarks} option.
1084 If you want to obtain code coverage results, run configure with the
1085 @code{--enable-coverage} option and run the @file{coverage.sh} script in
1086 the @file{contrib/} directory.
1089 @node Developing extensions for GNUnet using the gnunet-ext template
1090 @section Developing extensions for GNUnet using the gnunet-ext template
1092 For developers who want to write extensions for GNUnet we provide the
1093 gnunet-ext template to provide an easy to use skeleton.
1095 gnunet-ext contains the build environment and template files for the
1096 development of GNUnet services, command line tools, APIs and tests.
1098 First of all you have to obtain gnunet-ext from git:
1101 git clone https://gnunet.org/git/gnunet-ext.git
1104 The next step is to bootstrap and configure it. For configure you have to
1105 provide the path containing GNUnet with
1106 @code{--with-gnunet=/path/to/gnunet} and the prefix where you want the
1107 install the extension using @code{--prefix=/path/to/install}:
1111 ./configure --prefix=/path/to/install --with-gnunet=/path/to/gnunet
1114 When your GNUnet installation is not included in the default linker search
1115 path, you have to add @code{/path/to/gnunet} to the file
1116 @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the
1117 environmental variable @code{LD_LIBRARY_PATH} by using
1120 export LD_LIBRARY_PATH=/path/to/gnunet/lib
1123 @cindex writing testcases
1124 @node Writing testcases
1125 @section Writing testcases
1127 Ideally, any non-trivial GNUnet code should be covered by automated
1128 testcases. Testcases should reside in the same place as the code that is
1129 being tested. The name of source files implementing tests should begin
1130 with @code{test_} followed by the name of the file that contains
1131 the code that is being tested.
1133 Testcases in GNUnet should be integrated with the autotools build system.
1134 This way, developers and anyone building binary packages will be able to
1135 run all testcases simply by running @code{make check}. The final
1136 testcases shipped with the distribution should output at most some brief
1137 progress information and not display debug messages by default. The
1138 success or failure of a testcase must be indicated by returning zero
1139 (success) or non-zero (failure) from the main method of the testcase.
1140 The integration with the autotools is relatively straightforward and only
1141 requires modifications to the @file{Makefile.am} in the directory
1142 containing the testcase. For a testcase testing the code in @file{foo.c}
1143 the @file{Makefile.am} would contain the following lines:
1146 check_PROGRAMS = test_foo
1147 TESTS = $(check_PROGRAMS)
1148 test_foo_SOURCES = test_foo.c
1149 test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la
1152 Naturally, other libraries used by the testcase may be specified in the
1153 @code{LDADD} directive as necessary.
1155 Often testcases depend on additional input files, such as a configuration
1156 file. These support files have to be listed using the @code{EXTRA_DIST}
1157 directive in order to ensure that they are included in the distribution.
1162 EXTRA_DIST = test_foo_data.conf
1165 Executing @code{make check} will run all testcases in the current
1166 directory and all subdirectories. Testcases can be compiled individually
1167 by running @code{make test_foo} and then invoked directly using
1168 @code{./test_foo}. Note that due to the use of plugins in GNUnet, it is
1169 typically necessary to run @code{make install} before running any
1170 testcases. Thus the canonical command @code{make check install} has to be
1171 changed to @code{make install check} for GNUnet.
1173 @c ***********************************************************************
1174 @cindex Building GNUnet
1175 @node Building GNUnet and its dependencies
1176 @section Building GNUnet and its dependencies
1178 In the following section we will outline how to build GNUnet and
1179 some of its dependencies. We will assume a fair amount of knowledge
1180 for building applications under UNIX-like systems. Furthermore we
1181 assume that the build environment is sane and that you are aware of
1182 any implications actions in this process could have.
1183 Instructions here can be seen as notes for developers (an extension to
1184 the 'HACKING' section in README) as well as package maintainers.
1185 @b{Users should rely on the available binary packages.}
1186 We will use Debian as an example Operating System environment. Substitute
1187 accordingly with your own Operating System environment.
1189 For the full list of dependencies, consult the appropriate, up-to-date
1190 section in the @file{README} file.
1192 First, we need to build or install (depending on your OS) the following
1193 packages. If you build them from source, build them in this exact order:
1196 libgpgerror, libgcrypt, libnettle, libunbound, GnuTLS (with libunbound
1200 After we have build and installed those packages, we continue with
1201 packages closer to GNUnet in this step: libgnurl (our libcurl fork),
1202 GNU libmicrohttpd, and GNU libextractor. Again, if your package manager
1203 provides one of these packages, use the packages provided from it
1204 unless you have good reasons (package version too old, conflicts, etc).
1205 We advise against compiling widely used packages such as GnuTLS
1206 yourself if your OS provides a variant already unless you take care
1207 of maintenance of the packages then.
1209 In the optimistic case, this command will give you all the dependencies:
1212 sudo apt-get install libgnurl libmicrohttpd libextractor
1215 From experience we know that at the very least libgnurl is not
1216 available in some environments. You could substitute libgnurl
1217 with libcurl, but we recommend to install libgnurl, as it gives
1218 you a predefined libcurl with the small set GNUnet requires. In
1219 the past namespaces of libcurl and libgnurl were shared, which
1220 caused problems when you wanted to integrate both of them in one
1221 Operating System. This has been resolved, and they can be installed
1225 @cindex compiling libgnurl
1226 GNUnet and some of its function depend on a limited subset of cURL/libcurl.
1227 Rather than trying to enforce a certain configuration on the world, we
1228 opted to maintain a microfork of it that ensures we can link against the
1229 right set of features. We called this specialized set of libcurl
1230 ``libgnurl''. It is fully ABI compatible with libcurl and currently used
1231 by GNUnet and some of its dependencies.
1233 We download libgnurl and its digital signature from the GNU fileserver,
1234 assuming @env{TMPDIR} exists.
1236 Note: TMPDIR might be @file{/tmp}, @env{TMPDIR}, @env{TMP} or any other
1237 location. For consistency we assume @env{TMPDIR} points to @file{/tmp}
1238 for the remainder of this section.
1242 wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z
1243 wget https://ftp.gnu.org/gnu/gnunet/gnurl-7.60.0.tar.Z.sig
1246 Next, verify the digital signature of the file:
1249 gpg --verify gnurl-7.60.0.tar.Z.sig
1252 If gpg fails, you might try with @command{gpg2} on your OS. If the error
1253 states that ``the key can not be found'' or it is unknown, you have to
1254 retrieve the key (A88C8ADD129828D7EAC02E52E22F9BBFEE348588) from a
1258 gpg --keyserver pgp.mit.edu --recv-keys A88C8ADD129828D7EAC02E52E22F9BBFEE348588
1261 and rerun the verification command.
1263 libgnurl will require the following packages to be present at runtime:
1264 gnutls (with DANE support / libunbound), libidn, zlib and at compile time:
1265 libtool, groff, perl, pkg-config, and python 2.7.
1267 Once you have verified that all the required packages are present on your
1268 system, we can proceed to compile libgnurl:
1271 tar -xvf gnurl-7.60.0.tar.Z
1273 sh configure --disable-ntlm-wb
1279 After you've compiled and installed libgnurl, we can proceed to building
1285 First, in addition to the GNUnet sources you might require downloading the
1286 latest version of various dependencies, depending on how recent the
1287 software versions in your distribution of GNU/Linux are.
1288 Most distributions do not include sufficiently recent versions of these
1290 Thus, a typically installation on a "modern" GNU/Linux distribution
1291 requires you to install the following dependencies (ideally in this
1295 @item libgpgerror and libgcrypt
1296 @item libnettle and libunbound (possibly from distribution), GnuTLS
1297 @item libgnurl (read the README)
1298 @item GNU libmicrohttpd
1299 @item GNU libextractor
1302 Make sure to first install the various mandatory and optional
1303 dependencies including development headers from your distribution.
1305 Other dependencies that you should strongly consider to install is a
1306 database (MySQL, sqlite or Postgres).
1307 The following instructions will assume that you installed at least sqlite.
1308 For most distributions you should be able to find pre-build packages for
1309 the database. Again, make sure to install the client libraries @b{and} the
1310 respective development headers (if they are packaged separately) as well.
1312 You can find specific, detailed instructions for installing of the
1313 dependencies (and possibly the rest of the GNUnet installation) in the
1314 platform-specific descriptions, which can be found in the Index.
1315 Please consult them now.
1316 If your distribution is not listed, please study the build
1317 instructions for Debian stable, carefully as you try to install the
1318 dependencies for your own distribution.
1319 Contributing additional instructions for further platforms is always
1321 Please take in mind that operating system development tends to move at
1322 a rather fast speed. Due to this you should be aware that some of
1323 the instructions could be outdated by the time you are reading this.
1324 If you find a mistake, please tell us about it (or even better: send
1325 a patch to the documentation to fix it!).
1327 Before proceeding further, please double-check the dependency list.
1328 Note that in addition to satisfying the dependencies, you might have to
1329 make sure that development headers for the various libraries are also
1331 There maybe files for other distributions, or you might be able to find
1332 equivalent packages for your distribution.
1334 While it is possible to build and install GNUnet without having root
1335 access, we will assume that you have full control over your system in
1337 First, you should create a system user @emph{gnunet} and an additional
1338 group @emph{gnunetdns}. On the GNU/Linux distributions Debian and Ubuntu,
1342 sudo adduser --system --home /var/lib/gnunet --group \
1343 --disabled-password gnunet
1344 sudo addgroup --system gnunetdns
1348 On other Unixes and GNU systems, this should have the same effect:
1351 sudo useradd --system --groups gnunet --home-dir /var/lib/gnunet
1352 sudo addgroup --system gnunetdns
1355 Now compile and install GNUnet using:
1358 tar xvf gnunet-@value{VERSION}.tar.gz
1359 cd gnunet-@value{VERSION}
1360 ./configure --with-sudo=sudo --with-nssdir=/lib
1365 If you want to be able to enable DEBUG-level log messages, add
1366 @code{--enable-logging=verbose} to the end of the
1367 @command{./configure} command.
1368 @code{DEBUG}-level log messages are in English only and
1369 should only be useful for developers (or for filing
1370 really detailed bug reports).
1373 Next, edit the file @file{/etc/gnunet.conf} to contain the following:
1377 START_SYSTEM_SERVICES = YES
1378 START_USER_SERVICES = NO
1382 You may need to update your @code{ld.so} cache to include
1383 files installed in @file{/usr/local/lib}:
1390 Then, switch from user @code{root} to user @code{gnunet} to start
1394 # su -s /bin/sh - gnunet
1395 $ gnunet-arm -c /etc/gnunet.conf -s
1398 You may also want to add the last line in the gnunet user's @file{crontab}
1399 prefixed with @code{@@reboot} so that it is executed whenever the system
1403 @@reboot /usr/local/bin/gnunet-arm -c /etc/gnunet.conf -s
1407 This will only start the system-wide GNUnet services.
1408 Type @command{exit} to get back your root shell.
1409 Now, you need to configure the per-user part. For each
1410 user that should get access to GNUnet on the system, run
1411 (replace alice with your username):
1414 sudo adduser alice gnunet
1418 to allow them to access the system-wide GNUnet services. Then, each
1419 user should create a configuration file @file{~/.config/gnunet.conf}
1424 START_SYSTEM_SERVICES = NO
1425 START_USER_SERVICES = YES
1426 DEFAULTSERVICES = gns
1430 and start the per-user services using
1433 $ gnunet-arm -c ~/.config/gnunet.conf -s
1437 Again, adding a @code{crontab} entry to autostart the peer is advised:
1440 @@reboot /usr/local/bin/gnunet-arm -c $HOME/.config/gnunet.conf -s
1444 Note that some GNUnet services (such as SOCKS5 proxies) may need a
1445 system-wide TCP port for each user.
1446 For those services, systems with more than one user may require each user
1447 to specify a different port number in their personal configuration file.
1449 Finally, the user should perform the basic initial setup for the GNU Name
1450 System (GNS) certificate authority. This is done by running:
1453 $ gnunet-gns-proxy-setup-ca
1457 The first generates the default zones, whereas the second setups the GNS
1458 Certificate Authority with the user's browser. Now, to activate GNS in the
1459 normal DNS resolution process, you need to edit your
1460 @file{/etc/nsswitch.conf} where you should find a line like this:
1463 hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4
1467 The exact details may differ a bit, which is fine. Add the text
1468 @emph{"gns [NOTFOUND=return]"} after @emph{"files"}.
1469 Keep in mind that we included a backslash ("\") here just for
1470 markup reasons. You should write the text below on @b{one line}
1471 and @b{without} the "\":
1474 hosts: files gns [NOTFOUND=return] mdns4_minimal \
1475 [NOTFOUND=return] dns mdns4
1478 @c FIXME: Document new behavior.
1479 You might want to make sure that @file{/lib/libnss_gns.so.2} exists on
1480 your system, it should have been created during the installation.
1483 @c **********************************************************************
1484 @cindex TESTING library
1485 @node TESTING library
1486 @section TESTING library
1488 The TESTING library is used for writing testcases which involve starting a
1489 single or multiple peers. While peers can also be started by testcases
1490 using the ARM subsystem, using TESTING library provides an elegant way to
1491 do this. The configurations of the peers are auto-generated from a given
1492 template to have non-conflicting port numbers ensuring that peers'
1493 services do not run into bind errors. This is achieved by testing ports'
1494 availability by binding a listening socket to them before allocating them
1495 to services in the generated configurations.
1497 An another advantage while using TESTING is that it shortens the testcase
1498 startup time as the hostkeys for peers are copied from a pre-computed set
1499 of hostkeys instead of generating them at peer startup which may take a
1500 considerable amount of time when starting multiple peers or on an embedded
1503 TESTING also allows for certain services to be shared among peers. This
1504 feature is invaluable when testing with multiple peers as it helps to
1505 reduce the number of services run per each peer and hence the total
1506 number of processes run per testcase.
1508 TESTING library only handles creating, starting and stopping peers.
1509 Features useful for testcases such as connecting peers in a topology are
1510 not available in TESTING but are available in the TESTBED subsystem.
1511 Furthermore, TESTING only creates peers on the localhost, however by
1512 using TESTBED testcases can benefit from creating peers across multiple
1517 * Finer control over peer stop::
1518 * Helper functions::
1519 * Testing with multiple processes::
1526 TESTING abstracts a group of peers as a TESTING system. All peers in a
1527 system have common hostname and no two services of these peers have a
1528 same port or a UNIX domain socket path.
1530 TESTING system can be created with the function
1531 @code{GNUNET_TESTING_system_create()} which returns a handle to the
1532 system. This function takes a directory path which is used for generating
1533 the configurations of peers, an IP address from which connections to the
1534 peers' services should be allowed, the hostname to be used in peers'
1535 configuration, and an array of shared service specifications of type
1536 @code{struct GNUNET_TESTING_SharedService}.
1538 The shared service specification must specify the name of the service to
1539 share, the configuration pertaining to that shared service and the
1540 maximum number of peers that are allowed to share a single instance of
1543 TESTING system created with @code{GNUNET_TESTING_system_create()} chooses
1544 ports from the default range @code{12000} - @code{56000} while
1545 auto-generating configurations for peers.
1546 This range can be customised with the function
1547 @code{GNUNET_TESTING_system_create_with_portrange()}. This function is
1548 similar to @code{GNUNET_TESTING_system_create()} except that it take 2
1549 additional parameters --- the start and end of the port range to use.
1551 A TESTING system is destroyed with the function
1552 @code{GNUNET_TESTING_system_destory()}. This function takes the handle of
1553 the system and a flag to remove the files created in the directory used
1554 to generate configurations.
1556 A peer is created with the function
1557 @code{GNUNET_TESTING_peer_configure()}. This functions takes the system
1558 handle, a configuration template from which the configuration for the peer
1559 is auto-generated and the index from where the hostkey for the peer has to
1560 be copied from. When successful, this function returns a handle to the
1561 peer which can be used to start and stop it and to obtain the identity of
1562 the peer. If unsuccessful, a NULL pointer is returned with an error
1563 message. This function handles the generated configuration to have
1564 non-conflicting ports and paths.
1566 Peers can be started and stopped by calling the functions
1567 @code{GNUNET_TESTING_peer_start()} and @code{GNUNET_TESTING_peer_stop()}
1568 respectively. A peer can be destroyed by calling the function
1569 @code{GNUNET_TESTING_peer_destroy}. When a peer is destroyed, the ports
1570 and paths in allocated in its configuration are reclaimed for usage in new
1573 @c ***********************************************************************
1574 @node Finer control over peer stop
1575 @subsection Finer control over peer stop
1577 Using @code{GNUNET_TESTING_peer_stop()} is normally fine for testcases.
1578 However, calling this function for each peer is inefficient when trying to
1579 shutdown multiple peers as this function sends the termination signal to
1580 the given peer process and waits for it to terminate. It would be faster
1581 in this case to send the termination signals to the peers first and then
1582 wait on them. This is accomplished by the functions
1583 @code{GNUNET_TESTING_peer_kill()} which sends a termination signal to the
1584 peer, and the function @code{GNUNET_TESTING_peer_wait()} which waits on
1587 Further finer control can be achieved by choosing to stop a peer
1588 asynchronously with the function @code{GNUNET_TESTING_peer_stop_async()}.
1589 This function takes a callback parameter and a closure for it in addition
1590 to the handle to the peer to stop. The callback function is called with
1591 the given closure when the peer is stopped. Using this function
1592 eliminates blocking while waiting for the peer to terminate.
1594 An asynchronous peer stop can be canceled by calling the function
1595 @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this
1596 function does not prevent the peer from terminating if the termination
1597 signal has already been sent to it. It does, however, cancels the
1598 callback to be called when the peer is stopped.
1600 @c ***********************************************************************
1601 @node Helper functions
1602 @subsection Helper functions
1604 Most of the testcases can benefit from an abstraction which configures a
1605 peer and starts it. This is provided by the function
1606 @code{GNUNET_TESTING_peer_run()}. This function takes the testing
1607 directory pathname, a configuration template, a callback and its closure.
1608 This function creates a peer in the given testing directory by using the
1609 configuration template, starts the peer and calls the given callback with
1612 The function @code{GNUNET_TESTING_peer_run()} starts the ARM service of
1613 the peer which starts the rest of the configured services. A similar
1614 function @code{GNUNET_TESTING_service_run} can be used to just start a
1615 single service of a peer. In this case, the peer's ARM service is not
1616 started; instead, only the given service is run.
1618 @c ***********************************************************************
1619 @node Testing with multiple processes
1620 @subsection Testing with multiple processes
1622 When testing GNUnet, the splitting of the code into a services and clients
1623 often complicates testing. The solution to this is to have the testcase
1624 fork @code{gnunet-service-arm}, ask it to start the required server and
1625 daemon processes and then execute appropriate client actions (to test the
1626 client APIs or the core module or both). If necessary, multiple ARM
1627 services can be forked using different ports (!) to simulate a network.
1628 However, most of the time only one ARM process is needed. Note that on
1629 exit, the testcase should shutdown ARM with a @code{TERM} signal (to give
1630 it the chance to cleanly stop its child processes).
1632 The following code illustrates spawning and killing an ARM process from a
1636 static void run (void *cls,
1638 const char *cfgfile,
1639 const struct GNUNET_CONFIGURATION_Handle *cfg) @{
1640 struct GNUNET_OS_Process *arm_pid;
1641 arm_pid = GNUNET_OS_start_process (NULL,
1643 "gnunet-service-arm",
1644 "gnunet-service-arm",
1648 /* do real test work here */
1649 if (0 != GNUNET_OS_process_kill (arm_pid, SIGTERM))
1651 (GNUNET_ERROR_TYPE_WARNING, "kill");
1652 GNUNET_assert (GNUNET_OK == GNUNET_OS_process_wait (arm_pid));
1653 GNUNET_OS_process_close (arm_pid); @}
1655 GNUNET_PROGRAM_run (argc, argv,
1664 An alternative way that works well to test plugins is to implement a
1665 mock-version of the environment that the plugin expects and then to
1666 simply load the plugin directly.
1668 @c ***********************************************************************
1669 @node Performance regression analysis with Gauger
1670 @section Performance regression analysis with Gauger
1672 To help avoid performance regressions, GNUnet uses Gauger. Gauger is a
1673 simple logging tool that allows remote hosts to send performance data to
1674 a central server, where this data can be analyzed and visualized. Gauger
1675 shows graphs of the repository revisions and the performance data recorded
1676 for each revision, so sudden performance peaks or drops can be identified
1677 and linked to a specific revision number.
1679 In the case of GNUnet, the buildbots log the performance data obtained
1680 during the tests after each build. The data can be accessed on GNUnet's
1683 The menu on the left allows to select either the results of just one
1684 build bot (under "Hosts") or review the data from all hosts for a given
1685 test result (under "Metrics"). In case of very different absolute value
1686 of the results, for instance arm vs. amd64 machines, the option
1687 "Normalize" on a metric view can help to get an idea about the
1688 performance evolution across all hosts.
1690 Using Gauger in GNUnet and having the performance of a module tracked over
1691 time is very easy. First of course, the testcase must generate some
1692 consistent metric, which makes sense to have logged. Highly volatile or
1693 random dependent metrics probably are not ideal candidates for meaningful
1694 regression detection.
1696 To start logging any value, just include @code{gauger.h} in your testcase
1697 code. Then, use the macro @code{GAUGER()} to make the Buildbots log
1698 whatever value is of interest for you to @code{gnunet.org}'s Gauger
1699 server. No setup is necessary as most Buildbots have already everything
1700 in place and new metrics are created on demand. To delete a metric, you
1701 need to contact a member of the GNUnet development team (a file will need
1702 to be removed manually from the respective directory).
1704 The code in the test should look like this:
1710 int main (int argc, char *argv[]) @{
1712 [run test, generate data]
1713 GAUGER("YOUR_MODULE",
1723 @item @strong{YOUR_MODULE} is a category in the gauger page and should be
1724 the name of the module or subsystem like "Core" or "DHT"
1725 @item @strong{METRIC} is
1726 the name of the metric being collected and should be concise and
1727 descriptive, like "PUT operations in sqlite-datastore".
1728 @item @strong{value} is the value
1729 of the metric that is logged for this run.
1730 @item @strong{UNIT} is the unit in
1731 which the value is measured, for instance "kb/s" or "kb of RAM/node".
1734 If you wish to use Gauger for your own project, you can grab a copy of the
1735 latest stable release or check out Gauger's Subversion repository.
1737 @cindex TESTBED Subsystem
1738 @node TESTBED Subsystem
1739 @section TESTBED Subsystem
1741 The TESTBED subsystem facilitates testing and measuring of multi-peer
1742 deployments on a single host or over multiple hosts.
1744 The architecture of the testbed module is divided into the following:
1747 @item Testbed API: An API which is used by the testing driver programs. It
1748 provides with functions for creating, destroying, starting, stopping
1751 @item Testbed service (controller): A service which is started through the
1752 Testbed API. This service handles operations to create, destroy, start,
1753 stop peers, connect them, modify their configurations.
1755 @item Testbed helper: When a controller has to be started on a host, the
1756 testbed API starts the testbed helper on that host which in turn starts
1757 the controller. The testbed helper receives a configuration for the
1758 controller through its stdin and changes it to ensure the controller
1759 doesn't run into any port conflict on that host.
1763 The testbed service (controller) is different from the other GNUnet
1764 services in that it is not started by ARM and is not supposed to be run
1765 as a daemon. It is started by the testbed API through a testbed helper.
1766 In a typical scenario involving multiple hosts, a controller is started
1767 on each host. Controllers take up the actual task of creating peers,
1768 starting and stopping them on the hosts they run.
1770 While running deployments on a single localhost the testbed API starts the
1771 testbed helper directly as a child process. When running deployments on
1772 remote hosts the testbed API starts Testbed Helpers on each remote host
1773 through remote shell. By default testbed API uses SSH as a remote shell.
1774 This can be changed by setting the environmental variable
1775 GNUNET_TESTBED_RSH_CMD to the required remote shell program. This
1776 variable can also contain parameters which are to be passed to the remote
1777 shell program. For e.g:
1780 export GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes \
1781 -o NoHostAuthenticationForLocalhost=yes %h"
1784 Substitutions are allowed in the command string above,
1785 this allows for substitutions through placemarks which begin with a `%'.
1786 At present the following substitutions are supported
1794 Note that the substitution placemark is replaced only when the
1795 corresponding field is available and only once. Specifying
1801 doesn't work either. If you want to user username substitutions for
1802 @command{SSH}, use the argument @code{-l} before the
1803 username substitution.
1810 The testbed API and the helper communicate through the helpers stdin and
1811 stdout. As the helper is started through a remote shell on remote hosts
1812 any output messages from the remote shell interfere with the communication
1813 and results in a failure while starting the helper. For this reason, it is
1814 suggested to use flags to make the remote shells produce no output
1815 messages and to have password-less logins. The default remote shell, SSH,
1816 the default options are:
1819 -o BatchMode=yes -o NoHostBasedAuthenticationForLocalhost=yes"
1822 Password-less logins should be ensured by using SSH keys.
1824 Since the testbed API executes the remote shell as a non-interactive
1825 shell, certain scripts like .bashrc, .profiler may not be executed. If
1826 this is the case testbed API can be forced to execute an interactive
1827 shell by setting up the environmental variable
1828 @code{GNUNET_TESTBED_RSH_CMD_SUFFIX} to a shell program.
1830 An example could be:
1833 export GNUNET_TESTBED_RSH_CMD_SUFFIX="sh -lc"
1836 The testbed API will then execute the remote shell program as:
1839 $GNUNET_TESTBED_RSH_CMD -p $port $dest $GNUNET_TESTBED_RSH_CMD_SUFFIX \
1840 gnunet-helper-testbed
1843 On some systems, problems may arise while starting testbed helpers if
1844 GNUnet is installed into a custom location since the helper may not be
1845 found in the standard path. This can be addressed by setting the variable
1846 `@code{HELPER_BINARY_PATH}' to the path of the testbed helper.
1847 Testbed API will then use this path to start helper binaries both
1848 locally and remotely.
1850 Testbed API can accessed by including the
1851 @file{gnunet_testbed_service.h} file and linking with
1852 @code{-lgnunettestbed}.
1854 @c ***********************************************************************
1856 * Supported Topologies::
1857 * Hosts file format::
1858 * Topology file format::
1859 * Testbed Barriers::
1860 * Automatic large-scale deployment in the PlanetLab testbed::
1864 @node Supported Topologies
1865 @subsection Supported Topologies
1867 While testing multi-peer deployments, it is often needed that the peers
1868 are connected in some topology. This requirement is addressed by the
1869 function @code{GNUNET_TESTBED_overlay_connect()} which connects any given
1870 two peers in the testbed.
1872 The API also provides a helper function
1873 @code{GNUNET_TESTBED_overlay_configure_topology()} to connect a given set
1874 of peers in any of the following supported topologies:
1878 @item @code{GNUNET_TESTBED_TOPOLOGY_CLIQUE}: All peers are connected with
1881 @item @code{GNUNET_TESTBED_TOPOLOGY_LINE}: Peers are connected to form a
1884 @item @code{GNUNET_TESTBED_TOPOLOGY_RING}: Peers are connected to form a
1887 @item @code{GNUNET_TESTBED_TOPOLOGY_2D_TORUS}: Peers are connected to
1888 form a 2 dimensional torus topology. The number of peers may not be a
1889 perfect square, in that case the resulting torus may not have the uniform
1890 poloidal and toroidal lengths
1892 @item @code{GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI}: Topology is generated
1893 to form a random graph. The number of links to be present should be given
1895 @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD}: Peers are connected to
1896 form a 2D Torus with some random links among them. The number of random
1897 links are to be given
1899 @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING}: Peers are
1900 connected to form a ring with some random links among them. The number of
1901 random links are to be given
1903 @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a
1904 topology where peer connectivity follows power law - new peers are
1905 connected with high probability to well connected peers.
1906 (See Emergence of Scaling in Random Networks. Science 286,
1908 (@uref{https://gnunet.org/git/bibliography.git/plain/docs/emergence_of_scaling_in_random_networks__barabasi_albert_science_286__1999.pdf, pdf}))
1910 @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information
1911 is loaded from a file. The path to the file has to be given.
1912 @xref{Topology file format}, for the format of this file.
1914 @item @code{GNUNET_TESTBED_TOPOLOGY_NONE}: No topology
1918 The above supported topologies can be specified respectively by setting
1919 the variable @code{OVERLAY_TOPOLOGY} to the following values in the
1920 configuration passed to Testbed API functions
1921 @code{GNUNET_TESTBED_test_run()} and
1922 @code{GNUNET_TESTBED_run()}:
1928 @item @code{2D_TORUS}
1930 @item @code{SMALL_WORLD}
1931 @item @code{SMALL_WORLD_RING}
1932 @item @code{SCALE_FREE}
1933 @item @code{FROM_FILE}
1938 Topologies @code{RANDOM}, @code{SMALL_WORLD} and @code{SMALL_WORLD_RING}
1939 require the option @code{OVERLAY_RANDOM_LINKS} to be set to the number of
1940 random links to be generated in the configuration. The option will be
1941 ignored for the rest of the topologies.
1943 Topology @code{SCALE_FREE} requires the options
1944 @code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers
1945 which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to
1946 how many peers a peer should be at least connected to.
1948 Similarly, the topology @code{FROM_FILE} requires the option
1949 @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing
1950 the topology information. This option is ignored for the rest of the
1951 topologies. @xref{Topology file format}, for the format of this file.
1953 @c ***********************************************************************
1954 @node Hosts file format
1955 @subsection Hosts file format
1957 The testbed API offers the function
1958 @code{GNUNET_TESTBED_hosts_load_from_file()} to load from a given file
1959 details about the hosts which testbed can use for deploying peers.
1960 This function is useful to keep the data about hosts
1961 separate instead of hard coding them in code.
1963 Another helper function from testbed API, @code{GNUNET_TESTBED_run()}
1964 also takes a hosts file name as its parameter. It uses the above
1965 function to populate the hosts data structures and start controllers to
1968 These functions require the hosts file to be of the following format:
1970 @item Each line is interpreted to have details about a host
1971 @item Host details should include the username to use for logging into the
1972 host, the hostname of the host and the port number to use for the remote
1973 shell program. All thee values should be given.
1974 @item These details should be given in the following format:
1976 <username>@@<hostname>:<port>
1980 Note that having canonical hostnames may cause problems while resolving
1981 the IP addresses (See this bug). Hence it is advised to provide the hosts'
1982 IP numerical addresses as hostnames whenever possible.
1984 @c ***********************************************************************
1985 @node Topology file format
1986 @subsection Topology file format
1988 A topology file describes how peers are to be connected. It should adhere
1989 to the following format for testbed to parse it correctly.
1991 Each line should begin with the target peer id. This should be followed by
1992 a colon(`:') and origin peer ids separated by `|'. All spaces except for
1993 newline characters are ignored. The API will then try to connect each
1994 origin peer to the target peer.
1996 For example, the following file will result in 5 overlay connections:
1997 [2->1], [3->1],[4->3], [0->3], [2->0]@
1998 @code{@ 1:2|3@ 3:4| 0@ 0: 2@ }
2000 @c ***********************************************************************
2001 @node Testbed Barriers
2002 @subsection Testbed Barriers
2004 The testbed subsystem's barriers API facilitates coordination among the
2005 peers run by the testbed and the experiment driver. The concept is
2006 similar to the barrier synchronisation mechanism found in parallel
2007 programming or multi-threading paradigms - a peer waits at a barrier upon
2008 reaching it until the barrier is reached by a predefined number of peers.
2009 This predefined number of peers required to cross a barrier is also called
2010 quorum. We say a peer has reached a barrier if the peer is waiting for the
2011 barrier to be crossed. Similarly a barrier is said to be reached if the
2012 required quorum of peers reach the barrier. A barrier which is reached is
2013 deemed as crossed after all the peers waiting on it are notified.
2015 The barriers API provides the following functions:
2017 @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to
2018 initialize a barrier in the experiment
2019 @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel
2020 a barrier which has been initialized before
2021 @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal
2022 barrier service that the caller has reached a barrier and is waiting for
2024 @item @strong{@code{GNUNET_TESTBED_barrier_wait_cancel()}:} function to
2025 stop waiting for a barrier to be crossed
2029 Among the above functions, the first two, namely
2030 @code{GNUNET_TESTBED_barrier_init()} and
2031 @code{GNUNET_TESTBED_barrier_cancel()} are used by experiment drivers. All
2032 barriers should be initialised by the experiment driver by calling
2033 @code{GNUNET_TESTBED_barrier_init()}. This function takes a name to
2034 identify the barrier, the quorum required for the barrier to be crossed
2035 and a notification callback for notifying the experiment driver when the
2036 barrier is crossed. @code{GNUNET_TESTBED_barrier_cancel()} cancels an
2037 initialised barrier and frees the resources allocated for it. This
2038 function can be called upon a initialised barrier before it is crossed.
2040 The remaining two functions @code{GNUNET_TESTBED_barrier_wait()} and
2041 @code{GNUNET_TESTBED_barrier_wait_cancel()} are used in the peer's
2042 processes. @code{GNUNET_TESTBED_barrier_wait()} connects to the local
2043 barrier service running on the same host the peer is running on and
2044 registers that the caller has reached the barrier and is waiting for the
2045 barrier to be crossed. Note that this function can only be used by peers
2046 which are started by testbed as this function tries to access the local
2047 barrier service which is part of the testbed controller service. Calling
2048 @code{GNUNET_TESTBED_barrier_wait()} on an uninitialised barrier results
2049 in failure. @code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the
2050 notification registered by @code{GNUNET_TESTBED_barrier_wait()}.
2053 @c ***********************************************************************
2058 @node Implementation
2059 @subsubsection Implementation
2061 Since barriers involve coordination between experiment driver and peers,
2062 the barrier service in the testbed controller is split into two
2063 components. The first component responds to the message generated by the
2064 barrier API used by the experiment driver (functions
2065 @code{GNUNET_TESTBED_barrier_init()} and
2066 @code{GNUNET_TESTBED_barrier_cancel()}) and the second component to the
2067 messages generated by barrier API used by peers (functions
2068 @code{GNUNET_TESTBED_barrier_wait()} and
2069 @code{GNUNET_TESTBED_barrier_wait_cancel()}).
2071 Calling @code{GNUNET_TESTBED_barrier_init()} sends a
2072 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT} message to the master
2073 controller. The master controller then registers a barrier and calls
2074 @code{GNUNET_TESTBED_barrier_init()} for each its subcontrollers. In this
2075 way barrier initialisation is propagated to the controller hierarchy.
2076 While propagating initialisation, any errors at a subcontroller such as
2077 timeout during further propagation are reported up the hierarchy back to
2078 the experiment driver.
2080 Similar to @code{GNUNET_TESTBED_barrier_init()},
2081 @code{GNUNET_TESTBED_barrier_cancel()} propagates
2082 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_CANCEL} message which causes
2083 controllers to remove an initialised barrier.
2085 The second component is implemented as a separate service in the binary
2086 `gnunet-service-testbed' which already has the testbed controller service.
2087 Although this deviates from the gnunet process architecture of having one
2088 service per binary, it is needed in this case as this component needs
2089 access to barrier data created by the first component. This component
2090 responds to @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages from
2091 local peers when they call @code{GNUNET_TESTBED_barrier_wait()}. Upon
2092 receiving @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} message, the
2093 service checks if the requested barrier has been initialised before and
2094 if it was not initialised, an error status is sent through
2095 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to the local
2096 peer and the connection from the peer is terminated. If the barrier is
2097 initialised before, the barrier's counter for reached peers is incremented
2098 and a notification is registered to notify the peer when the barrier is
2099 reached. The connection from the peer is left open.
2101 When enough peers required to attain the quorum send
2102 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT} messages, the controller
2103 sends a @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message to its
2104 parent informing that the barrier is crossed. If the controller has
2105 started further subcontrollers, it delays this message until it receives
2106 a similar notification from each of those subcontrollers. Finally, the
2107 barriers API at the experiment driver receives the
2108 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} when the barrier is
2109 reached at all the controllers.
2111 The barriers API at the experiment driver responds to the
2112 @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message by echoing it
2113 back to the master controller and notifying the experiment controller
2114 through the notification callback that a barrier has been crossed. The
2115 echoed @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS} message is
2116 propagated by the master controller to the controller hierarchy. This
2117 propagation triggers the notifications registered by peers at each of the
2118 controllers in the hierarchy. Note the difference between this downward
2119 propagation of the @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS}
2120 message from its upward propagation --- the upward propagation is needed
2121 for ensuring that the barrier is reached by all the controllers and the
2122 downward propagation is for triggering that the barrier is crossed.
2124 @cindex PlanetLab testbed
2125 @node Automatic large-scale deployment in the PlanetLab testbed
2126 @subsection Automatic large-scale deployment in the PlanetLab testbed
2128 PlanetLab is a testbed for computer networking and distributed systems
2129 research. It was established in 2002 and as of June 2010 was composed of
2130 1090 nodes at 507 sites worldwide.
2132 To automate the GNUnet we created a set of automation tools to simplify
2133 the large-scale deployment. We provide you a set of scripts you can use
2134 to deploy GNUnet on a set of nodes and manage your installation.
2136 Please also check @uref{https://gnunet.org/installation-fedora8-svn} and
2137 @uref{https://gnunet.org/installation-fedora12-svn} to find detailed
2138 instructions how to install GNUnet on a PlanetLab node.
2141 @c ***********************************************************************
2143 * PlanetLab Automation for Fedora8 nodes::
2144 * Install buildslave on PlanetLab nodes running fedora core 8::
2145 * Setup a new PlanetLab testbed using GPLMT::
2146 * Why do i get an ssh error when using the regex profiler?::
2149 @node PlanetLab Automation for Fedora8 nodes
2150 @subsubsection PlanetLab Automation for Fedora8 nodes
2152 @c ***********************************************************************
2153 @node Install buildslave on PlanetLab nodes running fedora core 8
2154 @subsubsection Install buildslave on PlanetLab nodes running fedora core 8
2155 @c ** Actually this is a subsubsubsection, but must be fixed differently
2156 @c ** as subsubsection is the lowest.
2158 Since most of the PlanetLab nodes are running the very old Fedora core 8
2159 image, installing the buildslave software is quite some pain. For our
2160 PlanetLab testbed we figured out how to install the buildslave software
2163 @c This is a very terrible way to suggest installing software.
2164 @c FIXME: Is there an official, safer way instead of blind-piping a
2166 @c FIXME: Use newer pypi URLs below.
2167 Install Distribute for Python:
2170 curl http://python-distribute.org/distribute_setup.py | sudo python
2173 Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not
2177 export PYPI=@value{PYPI-URL}
2178 wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz
2179 tar zvfz zope.interface-3.8.0.tar.gz
2180 cd zope.interface-3.8.0
2181 sudo python setup.py install
2184 Install the buildslave software (0.8.6 was the latest version):
2187 export GCODE="http://buildbot.googlecode.com/files"
2188 wget $GCODE/buildbot-slave-0.8.6p1.tar.gz
2189 tar xvfz buildbot-slave-0.8.6p1.tar.gz
2190 cd buildslave-0.8.6p1
2191 sudo python setup.py install
2194 The setup will download the matching twisted package and install it.
2195 It will also try to install the latest version of zope.interface which
2196 will fail to install. Buildslave will work anyway since version 3.8.0
2197 was installed before!
2199 @c ***********************************************************************
2200 @node Setup a new PlanetLab testbed using GPLMT
2201 @subsubsection Setup a new PlanetLab testbed using GPLMT
2204 @item Get a new slice and assign nodes
2205 Ask your PlanetLab PI to give you a new slice and assign the nodes you
2207 @item Install a buildmaster
2208 You can stick to the buildbot documentation:@
2209 @uref{http://buildbot.net/buildbot/docs/current/manual/installation.html}
2210 @item Install the buildslave software on all nodes
2211 To install the buildslave on all nodes assigned to your slice you can use
2212 the tasklist @code{install_buildslave_fc8.xml} provided with GPLMT:
2215 ./gplmt.py -c contrib/tumple_gnunet.conf -t \
2216 contrib/tasklists/install_buildslave_fc8.xml -a -p <planetlab password>
2219 @item Create the buildmaster configuration and the slave setup commands
2221 The master and the and the slaves have need to have credentials and the
2222 master has to have all nodes configured. This can be done with the
2223 @file{create_buildbot_configuration.py} script in the @file{scripts}
2226 This scripts takes a list of nodes retrieved directly from PlanetLab or
2227 read from a file and a configuration template and creates:
2230 @item a tasklist which can be executed with gplmt to setup the slaves
2231 @item a master.cfg file containing a PlanetLab nodes
2234 A configuration template is included in the <contrib>, most important is
2235 that the script replaces the following tags in the template:
2237 %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@
2238 %GPLMT_SCHEDULER_BUILDERS
2240 Create configuration for all nodes assigned to a slice:
2243 ./create_buildbot_configuration.py -u <planetlab username> \
2244 -p <planetlab password> -s <slice> -m <buildmaster+port> \
2248 Create configuration for some nodes in a file:
2251 ./create_buildbot_configuration.p -f <node_file> \
2252 -m <buildmaster+port> -t <template>
2255 @item Copy the @file{master.cfg} to the buildmaster and start it
2256 Use @code{buildbot start <basedir>} to start the server
2257 @item Setup the buildslaves
2260 @c ***********************************************************************
2261 @node Why do i get an ssh error when using the regex profiler?
2262 @subsubsection Why do i get an ssh error when using the regex profiler?
2264 Why do i get an ssh error "Permission denied (publickey,password)." when
2265 using the regex profiler although passwordless ssh to localhost works
2266 using publickey and ssh-agent?
2268 You have to generate a public/private-key pair with no password:@
2269 @code{ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_localhost}@
2270 and then add the following to your ~/.ssh/config file:
2272 @code{Host 127.0.0.1@ IdentityFile ~/.ssh/id_localhost}
2274 now make sure your hostsfile looks like
2277 [USERNAME]@@127.0.0.1:22@
2278 [USERNAME]@@127.0.0.1:22
2281 You can test your setup by running @code{ssh 127.0.0.1} in a
2282 terminal and then in the opened session run it again.
2283 If you were not asked for a password on either login,
2284 then you should be good to go.
2286 @cindex TESTBED Caveats
2287 @node TESTBED Caveats
2288 @subsection TESTBED Caveats
2290 This section documents a few caveats when using the GNUnet testbed
2293 @c ***********************************************************************
2295 * CORE must be started::
2296 * ATS must want the connections::
2299 @node CORE must be started
2300 @subsubsection CORE must be started
2302 A uncomplicated issue is bug #3993
2303 (@uref{https://gnunet.org/bugs/view.php?id=3993, https://gnunet.org/bugs/view.php?id=3993}):
2304 Your configuration MUST somehow ensure that for each peer the
2305 @code{CORE} service is started when the peer is setup, otherwise
2306 @code{TESTBED} may fail to connect peers when the topology is initialized,
2307 as @code{TESTBED} will start some @code{CORE} services but not
2308 necessarily all (but it relies on all of them running). The easiest way
2313 IMMEDIATE_START = YES
2317 in the configuration file.
2318 Alternatively, having any service that directly or indirectly depends on
2319 @code{CORE} being started with @code{IMMEDIATE_START} will also do.
2320 This issue largely arises if users try to over-optimize by not
2321 starting any services with @code{IMMEDIATE_START}.
2323 @c ***********************************************************************
2324 @node ATS must want the connections
2325 @subsubsection ATS must want the connections
2327 When TESTBED sets up connections, it only offers the respective HELLO
2328 information to the TRANSPORT service. It is then up to the ATS service to
2329 @strong{decide} to use the connection. The ATS service will typically
2330 eagerly establish any connection if the number of total connections is
2331 low (relative to bandwidth). Details may further depend on the
2332 specific ATS backend that was configured. If ATS decides to NOT establish
2333 a connection (even though TESTBED provided the required information), then
2334 that connection will count as failed for TESTBED. Note that you can
2335 configure TESTBED to tolerate a certain number of connection failures
2336 (see '-e' option of gnunet-testbed-profiler). This issue largely arises
2337 for dense overlay topologies, especially if you try to create cliques
2338 with more than 20 peers.
2340 @cindex libgnunetutil
2342 @section libgnunetutil
2344 libgnunetutil is the fundamental library that all GNUnet code builds upon.
2345 Ideally, this library should contain most of the platform dependent code
2346 (except for user interfaces and really special needs that only few
2347 applications have). It is also supposed to offer basic services that most
2348 if not all GNUnet binaries require. The code of libgnunetutil is in the
2349 @file{src/util/} directory. The public interface to the library is in the
2350 gnunet_util.h header. The functions provided by libgnunetutil fall
2351 roughly into the following categories (in roughly the order of importance
2352 for new developers):
2355 @item logging (common_logging.c)
2356 @item memory allocation (common_allocation.c)
2357 @item endianess conversion (common_endian.c)
2358 @item internationalization (common_gettext.c)
2359 @item String manipulation (string.c)
2360 @item file access (disk.c)
2361 @item buffered disk IO (bio.c)
2362 @item time manipulation (time.c)
2363 @item configuration parsing (configuration.c)
2364 @item command-line handling (getopt*.c)
2365 @item cryptography (crypto_*.c)
2366 @item data structures (container_*.c)
2367 @item CPS-style scheduling (scheduler.c)
2368 @item Program initialization (program.c)
2369 @item Networking (network.c, client.c, server*.c, service.c)
2370 @item message queuing (mq.c)
2371 @item bandwidth calculations (bandwidth.c)
2372 @item Other OS-related (os*.c, plugin.c, signal.c)
2373 @item Pseudonym management (pseudonym.c)
2376 It should be noted that only developers that fully understand this entire
2377 API will be able to write good GNUnet code.
2379 Ideally, porting GNUnet should only require porting the gnunetutil
2380 library. More testcases for the gnunetutil APIs are therefore a great
2381 way to make porting of GNUnet easier.
2385 * Interprocess communication API (IPC)::
2386 * Cryptography API::
2387 * Message Queue API::
2389 * Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps::
2390 * CONTAINER_MDLL API::
2398 GNUnet is able to log its activity, mostly for the purposes of debugging
2399 the program at various levels.
2401 @file{gnunet_common.h} defines several @strong{log levels}:
2404 @item ERROR for errors (really problematic situations, often leading to
2406 @item WARNING for warnings (troubling situations that might have
2407 negative consequences, although not fatal)
2408 @item INFO for various information.
2409 Used somewhat rarely, as GNUnet statistics is used to hold and display
2410 most of the information that users might find interesting.
2411 @item DEBUG for debugging.
2412 Does not produce much output on normal builds, but when extra logging is
2413 enabled at compile time, a staggering amount of data is outputted under
2418 Normal builds of GNUnet (configured with @code{--enable-logging[=yes]})
2419 are supposed to log nothing under DEBUG level. The
2420 @code{--enable-logging=verbose} configure option can be used to create a
2421 build with all logging enabled. However, such build will produce large
2422 amounts of log data, which is inconvenient when one tries to hunt down a
2425 To mitigate this problem, GNUnet provides facilities to apply a filter to
2429 @item Logging by default When no log levels are configured in any other
2430 way (see below), GNUnet will default to the WARNING log level. This
2431 mostly applies to GNUnet command line utilities, services and daemons;
2432 tests will always set log level to WARNING or, if
2433 @code{--enable-logging=verbose} was passed to configure, to DEBUG. The
2434 default level is suggested for normal operation.
2435 @item The -L option Most GNUnet executables accept an "-L loglevel" or
2436 "--log=loglevel" option. If used, it makes the process set a global log
2437 level to "loglevel". Thus it is possible to run some processes
2438 with -L DEBUG, for example, and others with -L ERROR to enable specific
2439 settings to diagnose problems with a particular process.
2440 @item Configuration files. Because GNUnet
2441 service and daemon processes are usually launched by gnunet-arm, it is not
2442 possible to pass different custom command line options directly to every
2443 one of them. The options passed to @code{gnunet-arm} only affect
2444 gnunet-arm and not the rest of GNUnet. However, one can specify a
2445 configuration key "OPTIONS" in the section that corresponds to a service
2446 or a daemon, and put a value of "-L loglevel" there. This will make the
2447 respective service or daemon set its log level to "loglevel" (as the
2448 value of OPTIONS will be passed as a command-line argument).
2450 To specify the same log level for all services without creating separate
2451 "OPTIONS" entries in the configuration for each one, the user can specify
2452 a config key "GLOBAL_POSTFIX" in the [arm] section of the configuration
2453 file. The value of GLOBAL_POSTFIX will be appended to all command lines
2454 used by the ARM service to run other services. It can contain any option
2455 valid for all GNUnet commands, thus in particular the "-L loglevel"
2456 option. The ARM service itself is, however, unaffected by GLOBAL_POSTFIX;
2457 to set log level for it, one has to specify "OPTIONS" key in the [arm]
2459 @item Environment variables.
2460 Setting global per-process log levels with "-L loglevel" does not offer
2461 sufficient log filtering granularity, as one service will call interface
2462 libraries and supporting libraries of other GNUnet services, potentially
2463 producing lots of debug log messages from these libraries. Also, changing
2464 the config file is not always convenient (especially when running the
2465 GNUnet test suite).@ To fix that, and to allow GNUnet to use different
2466 log filtering at runtime without re-compiling the whole source tree, the
2467 log calls were changed to be configurable at run time. To configure them
2468 one has to define environment variables "GNUNET_FORCE_LOGFILE",
2469 "GNUNET_LOG" and/or "GNUNET_FORCE_LOG":
2472 @item "GNUNET_LOG" only affects the logging when no global log level is
2473 configured by any other means (that is, the process does not explicitly
2474 set its own log level, there are no "-L loglevel" options on command line
2475 or in configuration files), and can be used to override the default
2478 @item "GNUNET_FORCE_LOG" will completely override any other log
2479 configuration options given.
2481 @item "GNUNET_FORCE_LOGFILE" will completely override the location of the
2482 file to log messages to. It should contain a relative or absolute file
2483 name. Setting GNUNET_FORCE_LOGFILE is equivalent to passing
2484 "--log-file=logfile" or "-l logfile" option (see below). It supports "[]"
2485 format in file names, but not "@{@}" (see below).
2489 Because environment variables are inherited by child processes when they
2490 are launched, starting or re-starting the ARM service with these
2491 variables will propagate them to all other services.
2493 "GNUNET_LOG" and "GNUNET_FORCE_LOG" variables must contain a specially
2494 formatted @strong{logging definition} string, which looks like this:@
2496 @c FIXME: Can we close this with [/component] instead?
2498 [component];[file];[function];[from_line[-to_line]];loglevel[/component...]
2501 That is, a logging definition consists of definition entries, separated by
2502 slashes ('/'). If only one entry is present, there is no need to add a
2503 slash to its end (although it is not forbidden either).@ All definition
2504 fields (component, file, function, lines and loglevel) are mandatory, but
2505 (except for the loglevel) they can be empty. An empty field means
2506 "match anything". Note that even if fields are empty, the semicolon (';')
2507 separators must be present.@ The loglevel field is mandatory, and must
2508 contain one of the log level names (ERROR, WARNING, INFO or DEBUG).@
2509 The lines field might contain one non-negative number, in which case it
2510 matches only one line, or a range "from_line-to_line", in which case it
2511 matches any line in the interval [from_line;to_line] (that is, including
2512 both start and end line).@ GNUnet mostly defaults component name to the
2513 name of the service that is implemented in a process ('transport',
2514 'core', 'peerinfo', etc), but logging calls can specify custom component
2515 names using @code{GNUNET_log_from}.@ File name and function name are
2516 provided by the compiler (__FILE__ and __FUNCTION__ built-ins).
2518 Component, file and function fields are interpreted as non-extended
2519 regular expressions (GNU libc regex functions are used). Matching is
2520 case-sensitive, "^" and "$" will match the beginning and the end of the
2521 text. If a field is empty, its contents are automatically replaced with
2522 a ".*" regular expression, which matches anything. Matching is done in
2523 the default way, which means that the expression matches as long as it's
2524 contained anywhere in the string. Thus "GNUNET_" will match both
2525 "GNUNET_foo" and "BAR_GNUNET_BAZ". Use '^' and/or '$' to make sure that
2526 the expression matches at the start and/or at the end of the string.
2527 The semicolon (';') can't be escaped, and GNUnet will not use it in
2528 component names (it can't be used in function names and file names
2534 Every logging call in GNUnet code will be (at run time) matched against
2535 the log definitions passed to the process. If a log definition fields are
2536 matching the call arguments, then the call log level is compared the the
2537 log level of that definition. If the call log level is less or equal to
2538 the definition log level, the call is allowed to proceed. Otherwise the
2539 logging call is forbidden, and nothing is logged. If no definitions
2540 matched at all, GNUnet will use the global log level or (if a global log
2541 level is not specified) will default to WARNING (that is, it will allow
2542 the call to proceed, if its level is less or equal to the global log
2543 level or to WARNING).
2545 That is, definitions are evaluated from left to right, and the first
2546 matching definition is used to allow or deny the logging call. Thus it is
2547 advised to place narrow definitions at the beginning of the logdef
2548 string, and generic definitions - at the end.
2550 Whether a call is allowed or not is only decided the first time this
2551 particular call is made. The evaluation result is then cached, so that
2552 any attempts to make the same call later will be allowed or disallowed
2553 right away. Because of that runtime log level evaluation should not
2554 significantly affect the process performance.
2555 Log definition parsing is only done once, at the first call to
2556 @code{GNUNET_log_setup ()} made by the process (which is usually done soon after
2559 At the moment of writing there is no way to specify logging definitions
2560 from configuration files, only via environment variables.
2562 At the moment GNUnet will stop processing a log definition when it
2563 encounters an error in definition formatting or an error in regular
2564 expression syntax, and will not report the failure in any way.
2567 @c ***********************************************************************
2571 * Updated behavior of GNUNET_log::
2575 @subsubsection Examples
2579 @item @code{GNUNET_FORCE_LOG=";;;;DEBUG" gnunet-arm -s} Start GNUnet
2580 process tree, running all processes with DEBUG level (one should be
2581 careful with it, as log files will grow at alarming rate!)
2582 @item @code{GNUNET_FORCE_LOG="core;;;;DEBUG" gnunet-arm -s} Start GNUnet
2583 process tree, running the core service under DEBUG level (everything else
2584 will use configured or default level).
2586 @item Start GNUnet process tree, allowing any logging calls from
2587 gnunet-service-transport_validation.c (everything else will use
2588 configured or default level).
2591 GNUNET_FORCE_LOG=";gnunet-service-transport_validation.c;;; DEBUG" \
2595 @item Start GNUnet process tree, allowing any logging calls from
2596 gnunet-gnunet-service-fs_push.c (everything else will use configured or
2600 GNUNET_FORCE_LOG="fs;gnunet-service-fs_push.c;;;DEBUG" gnunet-arm -s
2603 @item Start GNUnet process tree, allowing any logging calls from the
2604 GNUNET_NETWORK_socket_select function (everything else will use
2605 configured or default level).
2608 GNUNET_FORCE_LOG=";;GNUNET_NETWORK_socket_select;;DEBUG" gnunet-arm -s
2611 @item Start GNUnet process tree, allowing any logging calls from the
2612 components that have "transport" in their names, and are made from
2613 function that have "send" in their names. Everything else will be allowed
2614 to be logged only if it has WARNING level.
2617 GNUNET_FORCE_LOG="transport.*;;.*send.*;;DEBUG/;;;;WARNING" gnunet-arm -s
2623 On Windows, one can use batch files to run GNUnet processes with special
2624 environment variables, without affecting the whole system. Such batch
2625 file will look like this:
2628 set GNUNET_FORCE_LOG=;;do_transmit;;DEBUG@ gnunet-arm -s
2631 (note the absence of double quotes in the environment variable definition,
2632 as opposed to earlier examples, which use the shell).
2633 Another limitation, on Windows, GNUNET_FORCE_LOGFILE @strong{MUST} be set
2634 in order to GNUNET_FORCE_LOG to work.
2639 @subsubsection Log files
2641 GNUnet can be told to log everything into a file instead of stderr (which
2642 is the default) using the "--log-file=logfile" or "-l logfile" option.
2643 This option can also be passed via command line, or from the "OPTION" and
2644 "GLOBAL_POSTFIX" configuration keys (see above). The file name passed
2645 with this option is subject to GNUnet filename expansion. If specified in
2646 "GLOBAL_POSTFIX", it is also subject to ARM service filename expansion,
2647 in particular, it may contain "@{@}" (left and right curly brace)
2648 sequence, which will be replaced by ARM with the name of the service.
2649 This is used to keep logs from more than one service separate, while only
2650 specifying one template containing "@{@}" in GLOBAL_POSTFIX.
2652 As part of a secondary file name expansion, the first occurrence of "[]"
2653 sequence ("left square brace" followed by "right square brace") in the
2654 file name will be replaced with a process identifier or the process when
2655 it initializes its logging subsystem. As a result, all processes will log
2656 into different files. This is convenient for isolating messages of a
2657 particular process, and prevents I/O races when multiple processes try to
2658 write into the file at the same time. This expansion is done
2659 independently of "@{@}" expansion that ARM service does (see above).
2661 The log file name that is specified via "-l" can contain format characters
2662 from the 'strftime' function family. For example, "%Y" will be replaced
2663 with the current year. Using "basename-%Y-%m-%d.log" would include the
2664 current year, month and day in the log file. If a GNUnet process runs for
2665 long enough to need more than one log file, it will eventually clean up
2666 old log files. Currently, only the last three log files (plus the current
2667 log file) are preserved. So once the fifth log file goes into use (so
2668 after 4 days if you use "%Y-%m-%d" as above), the first log file will be
2669 automatically deleted. Note that if your log file name only contains "%Y",
2670 then log files would be kept for 4 years and the logs from the first year
2671 would be deleted once year 5 begins. If you do not use any date-related
2672 string format codes, logs would never be automatically deleted by GNUnet.
2675 @c ***********************************************************************
2677 @node Updated behavior of GNUNET_log
2678 @subsubsection Updated behavior of GNUNET_log
2680 It's currently quite common to see constructions like this all over the
2685 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "MESH: client disconnected\n");
2689 The reason for the #if is not to avoid displaying the message when
2690 disabled (GNUNET_ERROR_TYPE takes care of that), but to avoid the
2691 compiler including it in the binary at all, when compiling GNUnet for
2692 platforms with restricted storage space / memory (MIPS routers,
2693 ARM plug computers / dev boards, etc).
2695 This presents several problems: the code gets ugly, hard to write and it
2696 is very easy to forget to include the #if guards, creating non-consistent
2697 code. A new change in GNUNET_log aims to solve these problems.
2699 @strong{This change requires to @file{./configure} with at least
2700 @code{--enable-logging=verbose} to see debug messages.}
2702 Here is an example of code with dense debug statements:
2705 switch (restrict_topology) @{
2706 case GNUNET_TESTING_TOPOLOGY_CLIQUE:#if VERBOSE_TESTING
2707 GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, _("Blacklisting all but clique
2708 topology\n")); #endif unblacklisted_connections = create_clique (pg,
2709 &remove_connections, BLACKLIST, GNUNET_NO); break; case
2710 GNUNET_TESTING_TOPOLOGY_SMALL_WORLD_RING: #if VERBOSE_TESTING GNUNET_log
2711 (GNUNET_ERROR_TYPE_DEBUG, _("Blacklisting all but small world (ring)
2712 topology\n")); #endif unblacklisted_connections = create_small_world_ring
2713 (pg,&remove_connections, BLACKLIST); break;
2717 Pretty hard to follow, huh?
2719 From now on, it is not necessary to include the #if / #endif statements to
2720 achieve the same behavior. The @code{GNUNET_log} and @code{GNUNET_log_from}
2722 care of it for you, depending on the configure option:
2725 @item If @code{--enable-logging} is set to @code{no}, the binary will
2726 contain no log messages at all.
2727 @item If @code{--enable-logging} is set to @code{yes}, the binary will
2728 contain no DEBUG messages, and therefore running with @command{-L DEBUG}
2730 no effect. Other messages (ERROR, WARNING, INFO, etc) will be included.
2731 @item If @code{--enable-logging} is set to @code{verbose}, or
2732 @code{veryverbose} the binary will contain DEBUG messages (still, it will
2733 be necessary to run with @command{-L DEBUG} or set the DEBUG config option
2739 If you are a developer:
2741 @item please make sure that you @code{./configure
2742 --enable-logging=@{verbose,veryverbose@}}, so you can see DEBUG messages.
2743 @item please remove the @code{#if} statements around @code{GNUNET_log
2744 (GNUNET_ERROR_TYPE_DEBUG, ...)} lines, to improve the readability of your
2748 Since now activating DEBUG automatically makes it VERBOSE and activates
2749 @strong{all} debug messages by default, you probably want to use the
2750 https://gnunet.org/logging functionality to filter only relevant messages.
2751 A suitable configuration could be:
2754 $ export GNUNET_FORCE_LOG="^YOUR_SUBSYSTEM$;;;;DEBUG/;;;;WARNING"
2757 Which will behave almost like enabling DEBUG in that subsystem before the
2758 change. Of course you can adapt it to your particular needs, this is only
2761 @cindex Interprocess communication API
2763 @node Interprocess communication API (IPC)
2764 @subsection Interprocess communication API (IPC)
2766 In GNUnet a variety of new message types might be defined and used in
2767 interprocess communication, in this tutorial we use the
2768 @code{struct AddressLookupMessage} as a example to introduce how to
2769 construct our own message type in GNUnet and how to implement the message
2770 communication between service and client.
2771 (Here, a client uses the @code{struct AddressLookupMessage} as a request
2772 to ask the server to return the address of any other peer connecting to
2776 @c ***********************************************************************
2778 * Define new message types::
2779 * Define message struct::
2780 * Client - Establish connection::
2781 * Client - Initialize request message::
2782 * Client - Send request and receive response::
2783 * Server - Startup service::
2784 * Server - Add new handles for specified messages::
2785 * Server - Process request message::
2786 * Server - Response to client::
2787 * Server - Notification of clients::
2788 * Conversion between Network Byte Order (Big Endian) and Host Byte Order::
2791 @node Define new message types
2792 @subsubsection Define new message types
2794 First of all, you should define the new message type in
2795 @file{gnunet_protocols.h}:
2798 // Request to look addresses of peers in server.
2799 #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP 29
2800 // Response to the address lookup request.
2801 #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY 30
2804 @c ***********************************************************************
2805 @node Define message struct
2806 @subsubsection Define message struct
2808 After the type definition, the specified message structure should also be
2809 described in the header file, e.g. transport.h in our case.
2812 struct AddressLookupMessage @{
2813 struct GNUNET_MessageHeader header;
2814 int32_t numeric_only GNUNET_PACKED;
2815 struct GNUNET_TIME_AbsoluteNBO timeout;
2816 uint32_t addrlen GNUNET_PACKED;
2817 /* followed by 'addrlen' bytes of the actual address, then
2818 followed by the 0-terminated name of the transport */ @};
2819 GNUNET_NETWORK_STRUCT_END
2823 Please note @code{GNUNET_NETWORK_STRUCT_BEGIN} and @code{GNUNET_PACKED}
2824 which both ensure correct alignment when sending structs over the network.
2829 @c ***********************************************************************
2830 @node Client - Establish connection
2831 @subsubsection Client - Establish connection
2835 At first, on the client side, the underlying API is employed to create a
2836 new connection to a service, in our example the transport service would be
2840 struct GNUNET_CLIENT_Connection *client;
2841 client = GNUNET_CLIENT_connect ("transport", cfg);
2844 @c ***********************************************************************
2845 @node Client - Initialize request message
2846 @subsubsection Client - Initialize request message
2849 When the connection is ready, we initialize the message. In this step,
2850 all the fields of the message should be properly initialized, namely the
2851 size, type, and some extra user-defined data, such as timeout, name of
2852 transport, address and name of transport.
2855 struct AddressLookupMessage *msg;
2856 size_t len = sizeof (struct AddressLookupMessage)
2858 + strlen (nameTrans)
2860 msg->header->size = htons (len);
2861 msg->header->type = htons
2862 (GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP);
2863 msg->timeout = GNUNET_TIME_absolute_hton (abs_timeout);
2864 msg->addrlen = htonl (addressLen);
2865 char *addrbuf = (char *) &msg[1];
2866 memcpy (addrbuf, address, addressLen);
2867 char *tbuf = &addrbuf[addressLen];
2868 memcpy (tbuf, nameTrans, strlen (nameTrans) + 1);
2871 Note that, here the functions @code{htonl}, @code{htons} and
2872 @code{GNUNET_TIME_absolute_hton} are applied to convert little endian
2873 into big endian, about the usage of the big/small endian order and the
2874 corresponding conversion function please refer to Introduction of
2875 Big Endian and Little Endian.
2877 @c ***********************************************************************
2878 @node Client - Send request and receive response
2879 @subsubsection Client - Send request and receive response
2882 @b{FIXME: This is very outdated, see the tutorial for the current API!}
2884 Next, the client would send the constructed message as a request to the
2885 service and wait for the response from the service. To accomplish this
2886 goal, there are a number of API calls that can be used. In this example,
2887 @code{GNUNET_CLIENT_transmit_and_get_response} is chosen as the most
2888 appropriate function to use.
2891 GNUNET_CLIENT_transmit_and_get_response
2892 (client, msg->header, timeout, GNUNET_YES, &address_response_processor,
2896 the argument @code{address_response_processor} is a function with
2897 @code{GNUNET_CLIENT_MessageHandler} type, which is used to process the
2898 reply message from the service.
2900 @node Server - Startup service
2901 @subsubsection Server - Startup service
2903 After receiving the request message, we run a standard GNUnet service
2904 startup sequence using @code{GNUNET_SERVICE_run}, as follows,
2907 int main(int argc, char**argv) @{
2908 GNUNET_SERVICE_run(argc, argv, "transport"
2909 GNUNET_SERVICE_OPTION_NONE, &run, NULL)); @}
2912 @c ***********************************************************************
2913 @node Server - Add new handles for specified messages
2914 @subsubsection Server - Add new handles for specified messages
2917 in the function above the argument @code{run} is used to initiate
2918 transport service,and defined like this:
2921 static void run (void *cls,
2922 struct GNUNET_SERVER_Handle *serv,
2923 const struct GNUNET_CONFIGURATION_Handle *cfg) @{
2924 GNUNET_SERVER_add_handlers (serv, handlers); @}
2928 Here, @code{GNUNET_SERVER_add_handlers} must be called in the run
2929 function to add new handlers in the service. The parameter
2930 @code{handlers} is a list of @code{struct GNUNET_SERVER_MessageHandler}
2931 to tell the service which function should be called when a particular
2932 type of message is received, and should be defined in this way:
2935 static struct GNUNET_SERVER_MessageHandler handlers[] = @{
2938 GNUNET_MESSAGE_TYPE_TRANSPORT_START,
2942 GNUNET_MESSAGE_TYPE_TRANSPORT_SEND,
2944 @{&handle_try_connect,
2946 GNUNET_MESSAGE_TYPE_TRANSPORT_TRY_CONNECT,
2947 sizeof (struct TryConnectMessage)
2949 @{&handle_address_lookup,
2951 GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP,
2961 As shown, the first member of the struct in the first area is a callback
2962 function, which is called to process the specified message types, given
2963 as the third member. The second parameter is the closure for the callback
2964 function, which is set to @code{NULL} in most cases, and the last
2965 parameter is the expected size of the message of this type, usually we
2966 set it to 0 to accept variable size, for special cases the exact size of
2967 the specified message also can be set. In addition, the terminator sign
2968 depicted as @code{@{NULL, NULL, 0, 0@}} is set in the last area.
2970 @c ***********************************************************************
2971 @node Server - Process request message
2972 @subsubsection Server - Process request message
2975 After the initialization of transport service, the request message would
2976 be processed. Before handling the main message data, the validity of this
2977 message should be checked out, e.g., to check whether the size of message
2981 size = ntohs (message->size);
2982 if (size < sizeof (struct AddressLookupMessage)) @{
2983 GNUNET_break_op (0);
2984 GNUNET_SERVER_receive_done (client, GNUNET_SYSERR);
2989 Note that, opposite to the construction method of the request message in
2990 the client, in the server the function @code{nothl} and @code{ntohs}
2991 should be employed during the extraction of the data from the message, so
2992 that the data in big endian order can be converted back into little
2993 endian order. See more in detail please refer to Introduction of
2994 Big Endian and Little Endian.
2996 Moreover in this example, the name of the transport stored in the message
2997 is a 0-terminated string, so we should also check whether the name of the
2998 transport in the received message is 0-terminated:
3001 nameTransport = (const char *) &address[addressLen];
3002 if (nameTransport[size - sizeof
3003 (struct AddressLookupMessage)
3004 - addressLen - 1] != '\0') @{
3005 GNUNET_break_op (0);
3006 GNUNET_SERVER_receive_done (client,
3011 Here, @code{GNUNET_SERVER_receive_done} should be called to tell the
3012 service that the request is done and can receive the next message. The
3013 argument @code{GNUNET_SYSERR} here indicates that the service didn't
3014 understand the request message, and the processing of this request would
3017 In comparison to the aforementioned situation, when the argument is equal
3018 to @code{GNUNET_OK}, the service would continue to process the request
3021 @c ***********************************************************************
3022 @node Server - Response to client
3023 @subsubsection Server - Response to client
3026 Once the processing of current request is done, the server should give the
3027 response to the client. A new @code{struct AddressLookupMessage} would be
3028 produced by the server in a similar way as the client did and sent to the
3029 client, but here the type should be
3030 @code{GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY} rather than
3031 @code{GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_LOOKUP} in client.
3033 struct AddressLookupMessage *msg;
3034 size_t len = sizeof (struct AddressLookupMessage)
3036 + strlen (nameTrans) + 1;
3037 msg->header->size = htons (len);
3038 msg->header->type = htons
3039 (GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY);
3043 struct GNUNET_SERVER_TransmitContext *tc;
3044 tc = GNUNET_SERVER_transmit_context_create (client);
3045 GNUNET_SERVER_transmit_context_append_data
3049 GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY);
3050 GNUNET_SERVER_transmit_context_run (tc, rtimeout);
3054 Note that, there are also a number of other APIs provided to the service
3055 to send the message.
3057 @c ***********************************************************************
3058 @node Server - Notification of clients
3059 @subsubsection Server - Notification of clients
3062 Often a service needs to (repeatedly) transmit notifications to a client
3063 or a group of clients. In these cases, the client typically has once
3064 registered for a set of events and then needs to receive a message
3065 whenever such an event happens (until the client disconnects). The use of
3066 a notification context can help manage message queues to clients and
3067 handle disconnects. Notification contexts can be used to send
3068 individualized messages to a particular client or to broadcast messages
3069 to a group of clients. An individualized notification might look like
3073 GNUNET_SERVER_notification_context_unicast(nc,
3080 Note that after processing the original registration message for
3081 notifications, the server code still typically needs to call
3082 @code{GNUNET_SERVER_receive_done} so that the client can transmit further
3083 messages to the server.
3085 @c ***********************************************************************
3086 @node Conversion between Network Byte Order (Big Endian) and Host Byte Order
3087 @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order
3088 @c %** subsub? it's a referenced page on the ipc document.
3091 Here we can simply comprehend big endian and little endian as Network Byte
3092 Order and Host Byte Order respectively. What is the difference between
3095 Usually in our host computer we store the data byte as Host Byte Order,
3096 for example, we store a integer in the RAM which might occupies 4 Byte,
3097 as Host Byte Order the higher Byte would be stored at the lower address
3098 of RAM, and the lower Byte would be stored at the higher address of RAM.
3099 However, contrast to this, Network Byte Order just take the totally
3100 opposite way to store the data, says, it will store the lower Byte at the
3101 lower address, and the higher Byte will stay at higher address.
3103 For the current communication of network, we normally exchange the
3104 information by surveying the data package, every two host wants to
3105 communicate with each other must send and receive data package through
3106 network. In order to maintain the identity of data through the
3107 transmission in the network, the order of the Byte storage must changed
3108 before sending and after receiving the data.
3110 There ten convenient functions to realize the conversion of Byte Order in
3111 GNUnet, as following:
3115 @item uint16_t htons(uint16_t hostshort) Convert host byte order to net
3116 byte order with short int
3117 @item uint32_t htonl(uint32_t hostlong) Convert host byte
3118 order to net byte order with long int
3119 @item uint16_t ntohs(uint16_t netshort)
3120 Convert net byte order to host byte order with short int
3122 ntohl(uint32_t netlong) Convert net byte order to host byte order with
3124 @item unsigned long long GNUNET_ntohll (unsigned long long netlonglong)
3125 Convert net byte order to host byte order with long long int
3126 @item unsigned long long GNUNET_htonll (unsigned long long hostlonglong)
3127 Convert host byte order to net byte order with long long int
3128 @item struct GNUNET_TIME_RelativeNBO GNUNET_TIME_relative_hton
3129 (struct GNUNET_TIME_Relative a) Convert relative time to network byte
3131 @item struct GNUNET_TIME_Relative GNUNET_TIME_relative_ntoh
3132 (struct GNUNET_TIME_RelativeNBO a) Convert relative time from network
3134 @item struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton
3135 (struct GNUNET_TIME_Absolute a) Convert relative time to network byte
3137 @item struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_ntoh
3138 (struct GNUNET_TIME_AbsoluteNBO a) Convert relative time from network
3142 @cindex Cryptography API
3143 @node Cryptography API
3144 @subsection Cryptography API
3147 The gnunetutil APIs provides the cryptographic primitives used in GNUnet.
3148 GNUnet uses 2048 bit RSA keys for the session key exchange and for signing
3149 messages by peers and most other public-key operations. Most researchers
3150 in cryptography consider 2048 bit RSA keys as secure and practically
3151 unbreakable for a long time. The API provides functions to create a fresh
3152 key pair, read a private key from a file (or create a new file if the
3153 file does not exist), encrypt, decrypt, sign, verify and extraction of
3154 the public key into a format suitable for network transmission.
3156 For the encryption of files and the actual data exchanged between peers
3157 GNUnet uses 256-bit AES encryption. Fresh, session keys are negotiated
3158 for every new connection.@ Again, there is no published technique to
3159 break this cipher in any realistic amount of time. The API provides
3160 functions for generation of keys, validation of keys (important for
3161 checking that decryptions using RSA succeeded), encryption and decryption.
3163 GNUnet uses SHA-512 for computing one-way hash codes. The API provides
3164 functions to compute a hash over a block in memory or over a file on disk.
3166 The crypto API also provides functions for randomizing a block of memory,
3167 obtaining a single random number and for generating a permutation of the
3168 numbers 0 to n-1. Random number generation distinguishes between WEAK and
3169 STRONG random number quality; WEAK random numbers are pseudo-random
3170 whereas STRONG random numbers use entropy gathered from the operating
3173 Finally, the crypto API provides a means to deterministically generate a
3174 1024-bit RSA key from a hash code. These functions should most likely not
3175 be used by most applications; most importantly,
3176 GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that
3177 should be considered secure for traditional applications of RSA.
3179 @cindex Message Queue API
3180 @node Message Queue API
3181 @subsection Message Queue API
3184 @strong{ Introduction }@
3185 Often, applications need to queue messages that
3186 are to be sent to other GNUnet peers, clients or services. As all of
3187 GNUnet's message-based communication APIs, by design, do not allow
3188 messages to be queued, it is common to implement custom message queues
3189 manually when they are needed. However, writing very similar code in
3190 multiple places is tedious and leads to code duplication.
3192 MQ (for Message Queue) is an API that provides the functionality to
3193 implement and use message queues. We intend to eventually replace all of
3194 the custom message queue implementations in GNUnet with MQ.
3196 @strong{ Basic Concepts }@
3197 The two most important entities in MQ are queues and envelopes.
3199 Every queue is backed by a specific implementation (e.g. for mesh, stream,
3200 connection, server client, etc.) that will actually deliver the queued
3201 messages. For convenience,@ some queues also allow to specify a list of
3202 message handlers. The message queue will then also wait for incoming
3203 messages and dispatch them appropriately.
3205 An envelope holds the the memory for a message, as well as metadata
3206 (Where is the envelope queued? What should happen after it has been
3207 sent?). Any envelope can only be queued in one message queue.
3209 @strong{ Creating Queues }@
3210 The following is a list of currently available message queues. Note that
3211 to avoid layering issues, message queues for higher level APIs are not
3212 part of @code{libgnunetutil}, but@ the respective API itself provides the
3213 queue implementation.
3217 @item @code{GNUNET_MQ_queue_for_connection_client}
3218 Transmits queued messages over a @code{GNUNET_CLIENT_Connection} handle.
3219 Also supports receiving with message handlers.
3221 @item @code{GNUNET_MQ_queue_for_server_client}
3222 Transmits queued messages over a @code{GNUNET_SERVER_Client} handle. Does
3223 not support incoming message handlers.
3225 @item @code{GNUNET_MESH_mq_create} Transmits queued messages over a
3226 @code{GNUNET_MESH_Tunnel} handle. Does not support incoming message
3229 @item @code{GNUNET_MQ_queue_for_callbacks} This is the most general
3230 implementation. Instead of delivering and receiving messages with one of
3231 GNUnet's communication APIs, implementation callbacks are called. Refer to
3232 "Implementing Queues" for a more detailed explanation.
3236 @strong{ Allocating Envelopes }@
3237 A GNUnet message (as defined by the GNUNET_MessageHeader) has three
3238 parts: The size, the type, and the body.
3240 MQ provides macros to allocate an envelope containing a message
3241 conveniently, automatically setting the size and type fields of the
3244 Consider the following simple message, with the body consisting of a
3245 single number value.
3246 @c why the empty code function?
3250 struct NumberMessage @{
3251 /** Type: GNUNET_MESSAGE_TYPE_EXAMPLE_1 */
3252 struct GNUNET_MessageHeader header;
3253 uint32_t number GNUNET_PACKED;
3257 An envelope containing an instance of the NumberMessage can be
3258 constructed like this:
3261 struct GNUNET_MQ_Envelope *ev;
3262 struct NumberMessage *msg;
3263 ev = GNUNET_MQ_msg (msg, GNUNET_MESSAGE_TYPE_EXAMPLE_1);
3264 msg->number = htonl (42);
3267 In the above code, @code{GNUNET_MQ_msg} is a macro. The return value is
3268 the newly allocated envelope. The first argument must be a pointer to some
3269 @code{struct} containing a @code{struct GNUNET_MessageHeader header}
3270 field, while the second argument is the desired message type, in host
3273 The @code{msg} pointer now points to an allocated message, where the
3274 message type and the message size are already set. The message's size is
3275 inferred from the type of the @code{msg} pointer: It will be set to
3276 'sizeof(*msg)', properly converted to network byte order.
3278 If the message body's size is dynamic, the the macro
3279 @code{GNUNET_MQ_msg_extra} can be used to allocate an envelope whose
3280 message has additional space allocated after the @code{msg} structure.
3282 If no structure has been defined for the message,
3283 @code{GNUNET_MQ_msg_header_extra} can be used to allocate additional space
3284 after the message header. The first argument then must be a pointer to a
3285 @code{GNUNET_MessageHeader}.
3287 @strong{Envelope Properties}@
3288 A few functions in MQ allow to set additional properties on envelopes:
3292 @item @code{GNUNET_MQ_notify_sent} Allows to specify a function that will
3293 be called once the envelope's message has been sent irrevocably.
3294 An envelope can be canceled precisely up to the@ point where the notify
3295 sent callback has been called.
3297 @item @code{GNUNET_MQ_disable_corking} No corking will be used when
3298 sending the message. Not every@ queue supports this flag, per default,
3299 envelopes are sent with corking.@
3304 @strong{Sending Envelopes}@
3305 Once an envelope has been constructed, it can be queued for sending with
3306 @code{GNUNET_MQ_send}.
3308 Note that in order to avoid memory leaks, an envelope must either be sent
3309 (the queue will free it) or destroyed explicitly with
3310 @code{GNUNET_MQ_discard}.
3312 @strong{Canceling Envelopes}@
3313 An envelope queued with @code{GNUNET_MQ_send} can be canceled with
3314 @code{GNUNET_MQ_cancel}. Note that after the notify sent callback has
3315 been called, canceling a message results in undefined behavior.
3316 Thus it is unsafe to cancel an envelope that does not have a notify sent
3317 callback. When canceling an envelope, it is not necessary@ to call
3318 @code{GNUNET_MQ_discard}, and the envelope can't be sent again.
3320 @strong{ Implementing Queues }@
3325 @subsection Service API
3328 Most GNUnet code lives in the form of services. Services are processes
3329 that offer an API for other components of the system to build on. Those
3330 other components can be command-line tools for users, graphical user
3331 interfaces or other services. Services provide their API using an IPC
3332 protocol. For this, each service must listen on either a TCP port or a
3333 UNIX domain socket; for this, the service implementation uses the server
3334 API. This use of server is exposed directly to the users of the service
3335 API. Thus, when using the service API, one is usually also often using
3336 large parts of the server API. The service API provides various
3337 convenience functions, such as parsing command-line arguments and the
3338 configuration file, which are not found in the server API.
3339 The dual to the service/server API is the client API, which can be used to
3342 The most common way to start a service is to use the
3343 @code{GNUNET_SERVICE_run} function from the program's main function.
3344 @code{GNUNET_SERVICE_run} will then parse the command line and
3345 configuration files and, based on the options found there,
3346 start the server. It will then give back control to the main
3347 program, passing the server and the configuration to the
3348 @code{GNUNET_SERVICE_Main} callback. @code{GNUNET_SERVICE_run}
3349 will also take care of starting the scheduler loop.
3350 If this is inappropriate (for example, because the scheduler loop
3351 is already running), @code{GNUNET_SERVICE_start} and
3352 related functions provide an alternative to @code{GNUNET_SERVICE_run}.
3354 When starting a service, the service_name option is used to determine
3355 which sections in the configuration file should be used to configure the
3356 service. A typical value here is the name of the @file{src/}
3357 sub-directory, for example @file{statistics}.
3358 The same string would also be given to
3359 @code{GNUNET_CLIENT_connect} to access the service.
3361 Once a service has been initialized, the program should use the
3362 @code{GNUNET_SERVICE_Main} callback to register message handlers
3363 using @code{GNUNET_SERVER_add_handlers}.
3364 The service will already have registered a handler for the
3367 @findex GNUNET_SERVICE_Options
3368 The option bitfield (@code{enum GNUNET_SERVICE_Options})
3369 determines how a service should behave during shutdown.
3370 There are three key strategies:
3374 @item instant (@code{GNUNET_SERVICE_OPTION_NONE})
3375 Upon receiving the shutdown
3376 signal from the scheduler, the service immediately terminates the server,
3377 closing all existing connections with clients.
3378 @item manual (@code{GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN})
3379 The service does nothing by itself
3380 during shutdown. The main program will need to take the appropriate
3381 action by calling GNUNET_SERVER_destroy or GNUNET_SERVICE_stop (depending
3382 on how the service was initialized) to terminate the service. This method
3383 is used by gnunet-service-arm and rather uncommon.
3384 @item soft (@code{GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN})
3385 Upon receiving the shutdown signal from the scheduler,
3386 the service immediately tells the server to stop
3387 listening for incoming clients. Requests from normal existing clients are
3388 still processed and the server/service terminates once all normal clients
3389 have disconnected. Clients that are not expected to ever disconnect (such
3390 as clients that monitor performance values) can be marked as 'monitor'
3391 clients using GNUNET_SERVER_client_mark_monitor. Those clients will
3392 continue to be processed until all 'normal' clients have disconnected.
3393 Then, the server will terminate, closing the monitor connections.
3394 This mode is for example used by 'statistics', allowing existing 'normal'
3395 clients to set (possibly persistent) statistic values before terminating.
3399 @c ***********************************************************************
3400 @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps
3401 @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps
3404 A commonly used data structure in GNUnet is a (multi-)hash map. It is most
3405 often used to map a peer identity to some data structure, but also to map
3406 arbitrary keys to values (for example to track requests in the distributed
3407 hash table or in file-sharing). As it is commonly used, the DHT is
3408 actually sometimes responsible for a large share of GNUnet's overall
3409 memory consumption (for some processes, 30% is not uncommon). The
3410 following text documents some API quirks (and their implications for
3411 applications) that were recently introduced to minimize the footprint of
3415 @c ***********************************************************************
3425 @subsubsection Analysis
3428 The main reason for the "excessive" memory consumption by the hash map is
3429 that GNUnet uses 512-bit cryptographic hash codes --- and the
3430 (multi-)hash map also uses the same 512-bit 'struct GNUNET_HashCode'. As
3431 a result, storing just the keys requires 64 bytes of memory for each key.
3432 As some applications like to keep a large number of entries in the hash
3433 map (after all, that's what maps are good for), 64 bytes per hash is
3434 significant: keeping a pointer to the value and having a linked list for
3435 collisions consume between 8 and 16 bytes, and 'malloc' may add about the
3436 same overhead per allocation, putting us in the 16 to 32 byte per entry
3437 ballpark. Adding a 64-byte key then triples the overall memory
3438 requirement for the hash map.
3440 To make things "worse", most of the time storing the key in the hash map
3441 is not required: it is typically already in memory elsewhere! In most
3442 cases, the values stored in the hash map are some application-specific
3443 struct that _also_ contains the hash. Here is a simplified example:
3447 struct GNUNET_HashCode key;
3448 unsigned int my_data; @};
3451 val = GNUNET_malloc (sizeof (struct MyValue));
3454 GNUNET_CONTAINER_multihashmap_put (map, &key, val, ...);
3457 This is a common pattern as later the entries might need to be removed,
3458 and at that time it is convenient to have the key immediately at hand:
3461 GNUNET_CONTAINER_multihashmap_remove (map, &val->key, val);
3465 Note that here we end up with two times 64 bytes for the key, plus maybe
3466 64 bytes total for the rest of the 'struct MyValue' and the map entry in
3467 the hash map. The resulting redundant storage of the key increases
3468 overall memory consumption per entry from the "optimal" 128 bytes to 192
3469 bytes. This is not just an extreme example: overheads in practice are
3470 actually sometimes close to those highlighted in this example. This is
3471 especially true for maps with a significant number of entries, as there
3472 we tend to really try to keep the entries small.
3474 @c ***********************************************************************
3476 @subsubsection Solution
3479 The solution that has now been implemented is to @strong{optionally}
3480 allow the hash map to not make a (deep) copy of the hash but instead have
3481 a pointer to the hash/key in the entry. This reduces the memory
3482 consumption for the key from 64 bytes to 4 to 8 bytes. However, it can
3483 also only work if the key is actually stored in the entry (which is the
3484 case most of the time) and if the entry does not modify the key (which in
3485 all of the code I'm aware of has been always the case if there key is
3486 stored in the entry). Finally, when the client stores an entry in the
3487 hash map, it @strong{must} provide a pointer to the key within the entry,
3488 not just a pointer to a transient location of the key. If
3489 the client code does not meet these requirements, the result is a dangling
3490 pointer and undefined behavior of the (multi-)hash map API.
3492 @c ***********************************************************************
3494 @subsubsection Migration
3497 To use the new feature, first check that the values contain the respective
3498 key (and never modify it). Then, all calls to
3499 @code{GNUNET_CONTAINER_multihashmap_put} on the respective map must be
3500 audited and most likely changed to pass a pointer into the value's struct.
3501 For the initial example, the new code would look like this:
3505 struct GNUNET_HashCode key;
3506 unsigned int my_data; @};
3509 val = GNUNET_malloc (sizeof (struct MyValue));
3510 val->key = key; val->my_data = 42;
3511 GNUNET_CONTAINER_multihashmap_put (map, &val->key, val, ...);
3515 Note that @code{&val} was changed to @code{&val->key} in the argument to
3516 the @code{put} call. This is critical as often @code{key} is on the stack
3517 or in some other transient data structure and thus having the hash map
3518 keep a pointer to @code{key} would not work. Only the key inside of
3519 @code{val} has the same lifetime as the entry in the map (this must of
3520 course be checked as well). Naturally, @code{val->key} must be
3521 initialized before the @code{put} call. Once all @code{put} calls have
3522 been converted and double-checked, you can change the call to create the
3527 GNUNET_CONTAINER_multihashmap_create (SIZE, GNUNET_NO);
3533 map = GNUNET_CONTAINER_multihashmap_create (SIZE, GNUNET_YES);
3536 If everything was done correctly, you now use about 60 bytes less memory
3537 per entry in @code{map}. However, if now (or in the future) any call to
3538 @code{put} does not ensure that the given key is valid until the entry is
3539 removed from the map, undefined behavior is likely to be observed.
3541 @c ***********************************************************************
3543 @subsubsection Conclusion
3546 The new optimization can is often applicable and can result in a
3547 reduction in memory consumption of up to 30% in practice. However, it
3548 makes the code less robust as additional invariants are imposed on the
3549 multi hash map client. Thus applications should refrain from enabling the
3550 new mode unless the resulting performance increase is deemed significant
3551 enough. In particular, it should generally not be used in new code (wait
3552 at least until benchmarks exist).
3554 @c ***********************************************************************
3556 @subsubsection Availability
3559 The new multi hash map code was committed in SVN 24319 (will be in GNUnet
3560 0.9.4). Various subsystems (transport, core, dht, file-sharing) were
3561 previously audited and modified to take advantage of the new capability.
3562 In particular, memory consumption of the file-sharing service is expected
3563 to drop by 20-30% due to this change.
3566 @cindex CONTAINER_MDLL API
3567 @node CONTAINER_MDLL API
3568 @subsection CONTAINER_MDLL API
3571 This text documents the GNUNET_CONTAINER_MDLL API. The
3572 GNUNET_CONTAINER_MDLL API is similar to the GNUNET_CONTAINER_DLL API in
3573 that it provides operations for the construction and manipulation of
3574 doubly-linked lists. The key difference to the (simpler) DLL-API is that
3575 the MDLL-version allows a single element (instance of a "struct") to be
3576 in multiple linked lists at the same time.
3578 Like the DLL API, the MDLL API stores (most of) the data structures for
3579 the doubly-linked list with the respective elements; only the 'head' and
3580 'tail' pointers are stored "elsewhere" --- and the application needs to
3581 provide the locations of head and tail to each of the calls in the
3582 MDLL API. The key difference for the MDLL API is that the "next" and
3583 "previous" pointers in the struct can no longer be simply called "next"
3584 and "prev" --- after all, the element may be in multiple doubly-linked
3585 lists, so we cannot just have one "next" and one "prev" pointer!
3587 The solution is to have multiple fields that must have a name of the
3588 format "next_XX" and "prev_XX" where "XX" is the name of one of the
3589 doubly-linked lists. Here is a simple example:
3592 struct MyMultiListElement @{
3593 struct MyMultiListElement *next_ALIST;
3594 struct MyMultiListElement *prev_ALIST;
3595 struct MyMultiListElement *next_BLIST;
3596 struct MyMultiListElement *prev_BLIST;
3603 Note that by convention, we use all-uppercase letters for the list names.
3604 In addition, the program needs to have a location for the head and tail
3605 pointers for both lists, for example:
3608 static struct MyMultiListElement *head_ALIST;
3609 static struct MyMultiListElement *tail_ALIST;
3610 static struct MyMultiListElement *head_BLIST;
3611 static struct MyMultiListElement *tail_BLIST;
3615 Using the MDLL-macros, we can now insert an element into the ALIST:
3618 GNUNET_CONTAINER_MDLL_insert (ALIST, head_ALIST, tail_ALIST, element);
3622 Passing "ALIST" as the first argument to MDLL specifies which of the
3623 next/prev fields in the 'struct MyMultiListElement' should be used. The
3624 extra "ALIST" argument and the "_ALIST" in the names of the
3625 next/prev-members are the only differences between the MDDL and DLL-API.
3626 Like the DLL-API, the MDLL-API offers functions for inserting (at head,
3627 at tail, after a given element) and removing elements from the list.
3628 Iterating over the list should be done by directly accessing the
3629 "next_XX" and/or "prev_XX" members.
3631 @cindex Automatic Restart Manager
3633 @node Automatic Restart Manager (ARM)
3634 @section Automatic Restart Manager (ARM)
3637 GNUnet's Automated Restart Manager (ARM) is the GNUnet service responsible
3638 for system initialization and service babysitting. ARM starts and halts
3639 services, detects configuration changes and restarts services impacted by
3640 the changes as needed. It's also responsible for restarting services in
3641 case of crashes and is planned to incorporate automatic debugging for
3642 diagnosing service crashes providing developers insights about crash
3643 reasons. The purpose of this document is to give GNUnet developer an idea
3644 about how ARM works and how to interact with it.
3647 * Basic functionality::
3648 * Key configuration options::
3649 * ARM - Availability::
3653 @c ***********************************************************************
3654 @node Basic functionality
3655 @subsection Basic functionality
3659 @item ARM source code can be found under "src/arm".@ Service processes are
3660 managed by the functions in "gnunet-service-arm.c" which is controlled
3661 with "gnunet-arm.c" (main function in that file is ARM's entry point).
3663 @item The functions responsible for communicating with ARM , starting and
3664 stopping services -including ARM service itself- are provided by the
3665 ARM API "arm_api.c".@ Function: GNUNET_ARM_connect() returns to the caller
3666 an ARM handle after setting it to the caller's context (configuration and
3667 scheduler in use). This handle can be used afterwards by the caller to
3668 communicate with ARM. Functions GNUNET_ARM_start_service() and
3669 GNUNET_ARM_stop_service() are used for starting and stopping services
3672 @item A typical example of using these basic ARM services can be found in
3673 file test_arm_api.c. The test case connects to ARM, starts it, then uses
3674 it to start a service "resolver", stops the "resolver" then stops "ARM".
3677 @c ***********************************************************************
3678 @node Key configuration options
3679 @subsection Key configuration options
3682 Configurations for ARM and services should be available in a .conf file
3683 (As an example, see test_arm_api_data.conf). When running ARM, the
3684 configuration file to use should be passed to the command:
3687 $ gnunet-arm -s -c configuration_to_use.conf
3690 If no configuration is passed, the default configuration file will be used
3691 (see GNUNET_PREFIX/share/gnunet/defaults.conf which is created from
3692 contrib/defaults.conf).@ Each of the services is having a section starting
3693 by the service name between square brackets, for example: "[arm]".
3694 The following options configure how ARM configures or interacts with the
3699 @item PORT Port number on which the service is listening for incoming TCP
3700 connections. ARM will start the services should it notice a request at
3703 @item HOSTNAME Specifies on which host the service is deployed. Note
3704 that ARM can only start services that are running on the local system
3705 (but will not check that the hostname matches the local machine name).
3706 This option is used by the @code{gnunet_client_lib.h} implementation to
3707 determine which system to connect to. The default is "localhost".
3709 @item BINARY The name of the service binary file.
3711 @item OPTIONS To be passed to the service.
3713 @item PREFIX A command to pre-pend to the actual command, for example,
3714 running a service with "valgrind" or "gdb"
3716 @item DEBUG Run in debug mode (much verbosity).
3718 @item START_ON_DEMAND ARM will listen to UNIX domain socket and/or TCP port of
3719 the service and start the service on-demand.
3721 @item IMMEDIATE_START ARM will always start this service when the peer
3724 @item ACCEPT_FROM IPv4 addresses the service accepts connections from.
3726 @item ACCEPT_FROM6 IPv6 addresses the service accepts connections from.
3731 Options that impact the operation of ARM overall are in the "[arm]"
3732 section. ARM is a normal service and has (except for START_ON_DEMAND) all of the
3733 options that other services do. In addition, ARM has the
3738 @item GLOBAL_PREFIX Command to be pre-pended to all services that are
3741 @item GLOBAL_POSTFIX Global option that will be supplied to all the
3742 services that are going to run.
3746 @c ***********************************************************************
3747 @node ARM - Availability
3748 @subsection ARM - Availability
3751 As mentioned before, one of the features provided by ARM is starting
3752 services on demand. Consider the example of one service "client" that
3753 wants to connect to another service a "server". The "client" will ask ARM
3754 to run the "server". ARM starts the "server". The "server" starts
3755 listening to incoming connections. The "client" will establish a
3756 connection with the "server". And then, they will start to communicate
3757 together.@ One problem with that scheme is that it's slow!@
3758 The "client" service wants to communicate with the "server" service at
3759 once and is not willing wait for it to be started and listening to
3760 incoming connections before serving its request.@ One solution for that
3761 problem will be that ARM starts all services as default services. That
3762 solution will solve the problem, yet, it's not quite practical, for some
3763 services that are going to be started can never be used or are going to
3764 be used after a relatively long time.@
3765 The approach followed by ARM to solve this problem is as follows:
3769 @item For each service having a PORT field in the configuration file and
3770 that is not one of the default services ( a service that accepts incoming
3771 connections from clients), ARM creates listening sockets for all addresses
3772 associated with that service.
3774 @item The "client" will immediately establish a connection with
3777 @item ARM --- pretending to be the "server" --- will listen on the
3778 respective port and notice the incoming connection from the "client"
3779 (but not accept it), instead
3781 @item Once there is an incoming connection, ARM will start the "server",
3782 passing on the listen sockets (now, the service is started and can do its
3785 @item Other client services now can directly connect directly to the
3790 @c ***********************************************************************
3792 @subsection Reliability
3794 One of the features provided by ARM, is the automatic restart of crashed
3795 services.@ ARM needs to know which of the running services died. Function
3796 "gnunet-service-arm.c/maint_child_death()" is responsible for that. The
3797 function is scheduled to run upon receiving a SIGCHLD signal. The
3798 function, then, iterates ARM's list of services running and monitors
3799 which service has died (crashed). For all crashing services, ARM restarts
3801 Now, considering the case of a service having a serious problem causing it
3802 to crash each time it's started by ARM. If ARM keeps blindly restarting
3803 such a service, we are going to have the pattern:
3804 start-crash-restart-crash-restart-crash and so forth!! Which is of course
3806 For that reason, ARM schedules the service to be restarted after waiting
3807 for some delay that grows exponentially with each crash/restart of that
3808 service.@ To clarify the idea, considering the following example:
3812 @item Service S crashed.
3814 @item ARM receives the SIGCHLD and inspects its list of services to find
3817 @item ARM finds S dead and schedules it for restarting after "backoff"
3818 time which is initially set to 1ms. ARM will double the backoff time
3819 correspondent to S (now backoff(S) = 2ms)
3821 @item Because there is a severe problem with S, it crashed again.
3823 @item Again ARM receives the SIGCHLD and detects that it's S again that's
3824 crashed. ARM schedules it for restarting but after its new backoff time
3825 (which became 2ms), and doubles its backoff time (now backoff(S) = 4).
3827 @item and so on, until backoff(S) reaches a certain threshold
3828 (@code{EXPONENTIAL_BACKOFF_THRESHOLD} is set to half an hour),
3829 after reaching it, backoff(S) will remain half an hour,
3830 hence ARM won't be busy for a lot of time trying to restart a
3831 problematic service.
3834 @cindex TRANSPORT Subsystem
3835 @node TRANSPORT Subsystem
3836 @section TRANSPORT Subsystem
3839 This chapter documents how the GNUnet transport subsystem works. The
3840 GNUnet transport subsystem consists of three main components: the
3841 transport API (the interface used by the rest of the system to access the
3842 transport service), the transport service itself (most of the interesting
3843 functions, such as choosing transports, happens here) and the transport
3844 plugins. A transport plugin is a concrete implementation for how two
3845 GNUnet peers communicate; many plugins exist, for example for
3846 communication via TCP, UDP, HTTP, HTTPS and others. Finally, the
3847 transport subsystem uses supporting code, especially the NAT/UPnP
3848 library to help with tasks such as NAT traversal.
3850 Key tasks of the transport service include:
3854 @item Create our HELLO message, notify clients and neighbours if our HELLO
3855 changes (using NAT library as necessary)
3857 @item Validate HELLOs from other peers (send PING), allow other peers to
3858 validate our HELLO's addresses (send PONG)
3860 @item Upon request, establish connections to other peers (using address
3861 selection from ATS subsystem) and maintain them (again using PINGs and
3862 PONGs) as long as desired
3864 @item Accept incoming connections, give ATS service the opportunity to
3865 switch communication channels
3867 @item Notify clients about peers that have connected to us or that have
3868 been disconnected from us
3870 @item If a (stateful) connection goes down unexpectedly (without explicit
3871 DISCONNECT), quickly attempt to recover (without notifying clients) but do
3872 notify clients quickly if reconnecting fails
3874 @item Send (payload) messages arriving from clients to other peers via
3875 transport plugins and receive messages from other peers, forwarding
3878 @item Enforce inbound traffic limits (using flow-control if it is
3879 applicable); outbound traffic limits are enforced by CORE, not by us (!)
3881 @item Enforce restrictions on P2P connection as specified by the blacklist
3882 configuration and blacklisting clients
3885 Note that the term "clients" in the list above really refers to the
3886 GNUnet-CORE service, as CORE is typically the only client of the
3890 * Address validation protocol::
3893 @node Address validation protocol
3894 @subsection Address validation protocol
3897 This section documents how the GNUnet transport service validates
3898 connections with other peers. It is a high-level description of the
3899 protocol necessary to understand the details of the implementation. It
3900 should be noted that when we talk about PING and PONG messages in this
3901 section, we refer to transport-level PING and PONG messages, which are
3902 different from core-level PING and PONG messages (both in implementation
3905 The goal of transport-level address validation is to minimize the chances
3906 of a successful man-in-the-middle attack against GNUnet peers on the
3907 transport level. Such an attack would not allow the adversary to decrypt
3908 the P2P transmissions, but a successful attacker could at least measure
3909 traffic volumes and latencies (raising the adversaries capabilities by
3910 those of a global passive adversary in the worst case). The scenarios we
3911 are concerned about is an attacker, Mallory, giving a @code{HELLO} to
3912 Alice that claims to be for Bob, but contains Mallory's IP address
3913 instead of Bobs (for some transport).
3914 Mallory would then forward the traffic to Bob (by initiating a
3915 connection to Bob and claiming to be Alice). As a further
3916 complication, the scheme has to work even if say Alice is behind a NAT
3917 without traversal support and hence has no address of her own (and thus
3918 Alice must always initiate the connection to Bob).
3920 An additional constraint is that @code{HELLO} messages do not contain a
3921 cryptographic signature since other peers must be able to edit
3922 (i.e. remove) addresses from the @code{HELLO} at any time (this was
3923 not true in GNUnet 0.8.x). A basic @strong{assumption} is that each peer
3924 knows the set of possible network addresses that it @strong{might}
3925 be reachable under (so for example, the external IP address of the
3926 NAT plus the LAN address(es) with the respective ports).
3928 The solution is the following. If Alice wants to validate that a given
3929 address for Bob is valid (i.e. is actually established @strong{directly}
3930 with the intended target), she sends a PING message over that connection
3931 to Bob. Note that in this case, Alice initiated the connection so only
3932 Alice knows which address was used for sure (Alice may be behind NAT, so
3933 whatever address Bob sees may not be an address Alice knows she has).
3934 Bob checks that the address given in the @code{PING} is actually one
3935 of Bob's addresses (ie: does not belong to Mallory), and if it is,
3936 sends back a @code{PONG} (with a signature that says that Bob
3937 owns/uses the address from the @code{PING}).
3938 Alice checks the signature and is happy if it is valid and the address
3939 in the @code{PONG} is the address Alice used.
3940 This is similar to the 0.8.x protocol where the @code{HELLO} contained a
3941 signature from Bob for each address used by Bob.
3942 Here, the purpose code for the signature is
3943 @code{GNUNET_SIGNATURE_PURPOSE_TRANSPORT_PONG_OWN}. After this, Alice will
3944 remember Bob's address and consider the address valid for a while (12h in
3945 the current implementation). Note that after this exchange, Alice only
3946 considers Bob's address to be valid, the connection itself is not
3947 considered 'established'. In particular, Alice may have many addresses
3948 for Bob that Alice considers valid.
3950 The @code{PONG} message is protected with a nonce/challenge against replay
3951 attacks (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay})
3952 and uses an expiration time for the signature (but those are almost
3953 implementation details).
3957 @section NAT library
3960 The goal of the GNUnet NAT library is to provide a general-purpose API for
3961 NAT traversal @strong{without} third-party support. So protocols that
3962 involve contacting a third peer to help establish a connection between
3963 two peers are outside of the scope of this API. That does not mean that
3964 GNUnet doesn't support involving a third peer (we can do this with the
3965 distance-vector transport or using application-level protocols), it just
3966 means that the NAT API is not concerned with this possibility. The API is
3967 written so that it will work for IPv6-NAT in the future as well as
3968 current IPv4-NAT. Furthermore, the NAT API is always used, even for peers
3969 that are not behind NAT --- in that case, the mapping provided is simply
3972 NAT traversal is initiated by calling @code{GNUNET_NAT_register}. Given a
3973 set of addresses that the peer has locally bound to (TCP or UDP), the NAT
3974 library will return (via callback) a (possibly longer) list of addresses
3975 the peer @strong{might} be reachable under. Internally, depending on the
3976 configuration, the NAT library will try to punch a hole (using UPnP) or
3977 just "know" that the NAT was manually punched and generate the respective
3978 external IP address (the one that should be globally visible) based on
3979 the given information.
3981 The NAT library also supports ICMP-based NAT traversal. Here, the other
3982 peer can request connection-reversal by this peer (in this special case,
3983 the peer is even allowed to configure a port number of zero). If the NAT
3984 library detects a connection-reversal request, it returns the respective
3985 target address to the client as well. It should be noted that
3986 connection-reversal is currently only intended for TCP, so other plugins
3987 @strong{must} pass @code{NULL} for the reversal callback. Naturally, the
3988 NAT library also supports requesting connection reversal from a remote
3989 peer (@code{GNUNET_NAT_run_client}).
3991 Once initialized, the NAT handle can be used to test if a given address is
3992 possibly a valid address for this peer (@code{GNUNET_NAT_test_address}).
3993 This is used for validating our addresses when generating PONGs.
3995 Finally, the NAT library contains an API to test if our NAT configuration
3996 is correct. Using @code{GNUNET_NAT_test_start} @strong{before} binding to
3997 the respective port, the NAT library can be used to test if the
3998 configuration works. The test function act as a local client, initialize
3999 the NAT traversal and then contact a @code{gnunet-nat-server} (running by
4000 default on @code{gnunet.org}) and ask for a connection to be established.
4001 This way, it is easy to test if the current NAT configuration is valid.
4003 @node Distance-Vector plugin
4004 @section Distance-Vector plugin
4007 The Distance Vector (DV) transport is a transport mechanism that allows
4008 peers to act as relays for each other, thereby connecting peers that would
4009 otherwise be unable to connect. This gives a larger connection set to
4010 applications that may work better with more peers to choose from (for
4011 example, File Sharing and/or DHT).
4013 The Distance Vector transport essentially has two functions. The first is
4014 "gossiping" connection information about more distant peers to directly
4015 connected peers. The second is taking messages intended for non-directly
4016 connected peers and encapsulating them in a DV wrapper that contains the
4017 required information for routing the message through forwarding peers. Via
4018 gossiping, optimal routes through the known DV neighborhood are discovered
4019 and utilized and the message encapsulation provides some benefits in
4020 addition to simply getting the message from the correct source to the
4023 The gossiping function of DV provides an up to date routing table of
4024 peers that are available up to some number of hops. We call this a
4025 fisheye view of the network (like a fish, nearby objects are known while
4026 more distant ones unknown). Gossip messages are sent only to directly
4027 connected peers, but they are sent about other knowns peers within the
4028 "fisheye distance". Whenever two peers connect, they immediately gossip
4029 to each other about their appropriate other neighbors. They also gossip
4030 about the newly connected peer to previously
4031 connected neighbors. In order to keep the routing tables up to date,
4032 disconnect notifications are propagated as gossip as well (because
4033 disconnects may not be sent/received, timeouts are also used remove
4034 stagnant routing table entries).
4036 Routing of messages via DV is straightforward. When the DV transport is
4037 notified of a message destined for a non-direct neighbor, the appropriate
4038 forwarding peer is selected, and the base message is encapsulated in a DV
4039 message which contains information about the initial peer and the intended
4040 recipient. At each forwarding hop, the initial peer is validated (the
4041 forwarding peer ensures that it has the initial peer in its neighborhood,
4042 otherwise the message is dropped). Next the base message is
4043 re-encapsulated in a new DV message for the next hop in the forwarding
4044 chain (or delivered to the current peer, if it has arrived at the
4047 Assume a three peer network with peers Alice, Bob and Carol. Assume that
4050 Alice <-> Bob and Bob <-> Carol
4054 are direct (e.g. over TCP or UDP transports) connections, but that
4055 Alice cannot directly connect to Carol.
4056 This may be the case due to NAT or firewall restrictions, or perhaps
4057 based on one of the peers respective configurations. If the Distance
4058 Vector transport is enabled on all three peers, it will automatically
4059 discover (from the gossip protocol) that Alice and Carol can connect via
4060 Bob and provide a "virtual" Alice <-> Carol connection. Routing between
4061 Alice and Carol happens as follows; Alice creates a message destined for
4062 Carol and notifies the DV transport about it. The DV transport at Alice
4063 looks up Carol in the routing table and finds that the message must be
4064 sent through Bob for Carol. The message is encapsulated setting Alice as
4065 the initiator and Carol as the destination and sent to Bob. Bob receives
4066 the messages, verifies that both Alice and Carol are known to Bob, and
4067 re-wraps the message in a new DV message for Carol.
4068 The DV transport at Carol receives this message, unwraps the original
4069 message, and delivers it to Carol as though it came directly from Alice.
4073 @section SMTP plugin
4076 This section describes the new SMTP transport plugin for GNUnet as it
4077 exists in the 0.7.x and 0.8.x branch. SMTP support is currently not
4078 available in GNUnet 0.9.x. This page also describes the transport layer
4079 abstraction (as it existed in 0.7.x and 0.8.x) in more detail and gives
4080 some benchmarking results. The performance results presented are quite
4081 old and maybe outdated at this point.
4084 @item Why use SMTP for a peer-to-peer transport?
4085 @item SMTPHow does it work?
4086 @item How do I configure my peer?
4087 @item How do I test if it works?
4088 @item How fast is it?
4089 @item Is there any additional documentation?
4094 * Why use SMTP for a peer-to-peer transport?::
4095 * How does it work?::
4096 * How do I configure my peer?::
4097 * How do I test if it works?::
4101 @node Why use SMTP for a peer-to-peer transport?
4102 @subsection Why use SMTP for a peer-to-peer transport?
4105 There are many reasons why one would not want to use SMTP:
4108 @item SMTP is using more bandwidth than TCP, UDP or HTTP
4109 @item SMTP has a much higher latency.
4110 @item SMTP requires significantly more computation (encoding and decoding
4111 time) for the peers.
4112 @item SMTP is significantly more complicated to configure.
4113 @item SMTP may be abused by tricking GNUnet into sending mail to@
4114 non-participating third parties.
4117 So why would anybody want to use SMTP?
4119 @item SMTP can be used to contact peers behind NAT boxes (in virtual
4121 @item SMTP can be used to circumvent policies that limit or prohibit
4122 peer-to-peer traffic by masking as "legitimate" traffic.
4123 @item SMTP uses E-mail addresses which are independent of a specific IP,
4124 which can be useful to address peers that use dynamic IP addresses.
4125 @item SMTP can be used to initiate a connection (e.g. initial address
4126 exchange) and peers can then negotiate the use of a more efficient
4127 protocol (e.g. TCP) for the actual communication.
4130 In summary, SMTP can for example be used to send a message to a peer
4131 behind a NAT box that has a dynamic IP to tell the peer to establish a
4132 TCP connection to a peer outside of the private network. Even an
4133 extraordinary overhead for this first message would be irrelevant in this
4136 @node How does it work?
4137 @subsection How does it work?
4140 When a GNUnet peer needs to send a message to another GNUnet peer that has
4141 advertised (only) an SMTP transport address, GNUnet base64-encodes the
4142 message and sends it in an E-mail to the advertised address. The
4143 advertisement contains a filter which is placed in the E-mail header,
4144 such that the receiving host can filter the tagged E-mails and forward it
4145 to the GNUnet peer process. The filter can be specified individually by
4146 each peer and be changed over time. This makes it impossible to censor
4147 GNUnet E-mail messages by searching for a generic filter.
4149 @node How do I configure my peer?
4150 @subsection How do I configure my peer?
4153 First, you need to configure @code{procmail} to filter your inbound E-mail
4154 for GNUnet traffic. The GNUnet messages must be delivered into a pipe, for
4155 example @code{/tmp/gnunet.smtp}. You also need to define a filter that is
4156 used by @command{procmail} to detect GNUnet messages. You are free to
4157 choose whichever filter you like, but you should make sure that it does
4158 not occur in your other E-mail. In our example, we will use
4159 @code{X-mailer: GNUnet}. The @code{~/.procmailrc} configuration file then
4166 # where do you want your other e-mail delivered to
4167 # (default: /var/spool/mail/)
4168 :0: /var/spool/mail/
4171 After adding this file, first make sure that your regular E-mail still
4172 works (e.g. by sending an E-mail to yourself). Then edit the GNUnet
4173 configuration. In the section @code{SMTP} you need to specify your E-mail
4174 address under @code{EMAIL}, your mail server (for outgoing mail) under
4175 @code{SERVER}, the filter (X-mailer: GNUnet in the example) under
4176 @code{FILTER} and the name of the pipe under @code{PIPE}.@ The completed
4177 section could then look like this:
4180 EMAIL = me@@mail.gnu.org MTU = 65000 SERVER = mail.gnu.org:25 FILTER =
4181 "X-mailer: GNUnet" PIPE = /tmp/gnunet.smtp
4184 Finally, you need to add @code{smtp} to the list of @code{TRANSPORTS} in
4185 the @code{GNUNETD} section. GNUnet peers will use the E-mail address that
4186 you specified to contact your peer until the advertisement times out.
4187 Thus, if you are not sure if everything works properly or if you are not
4188 planning to be online for a long time, you may want to configure this
4189 timeout to be short, e.g. just one hour. For this, set
4190 @code{HELLOEXPIRES} to @code{1} in the @code{GNUNETD} section.
4192 This should be it, but you may probably want to test it first.
4194 @node How do I test if it works?
4195 @subsection How do I test if it works?
4198 Any transport can be subjected to some rudimentary tests using the
4199 @code{gnunet-transport-check} tool. The tool sends a message to the local
4200 node via the transport and checks that a valid message is received. While
4201 this test does not involve other peers and can not check if firewalls or
4202 other network obstacles prohibit proper operation, this is a great
4203 testcase for the SMTP transport since it tests pretty much nearly all of
4206 @code{gnunet-transport-check} should only be used without running
4207 @code{gnunetd} at the same time. By default, @code{gnunet-transport-check}
4208 tests all transports that are specified in the configuration file. But
4209 you can specifically test SMTP by giving the option
4210 @code{--transport=smtp}.
4212 Note that this test always checks if a transport can receive and send.
4213 While you can configure most transports to only receive or only send
4214 messages, this test will only work if you have configured the transport
4215 to send and receive messages.
4217 @node How fast is it?
4218 @subsection How fast is it?
4221 We have measured the performance of the UDP, TCP and SMTP transport layer
4222 directly and when used from an application using the GNUnet core.
4223 Measuring just the transport layer gives the better view of the actual
4224 overhead of the protocol, whereas evaluating the transport from the
4225 application puts the overhead into perspective from a practical point of
4228 The loopback measurements of the SMTP transport were performed on three
4229 different machines spanning a range of modern SMTP configurations. We
4230 used a PIII-800 running RedHat 7.3 with the Purdue Computer Science
4231 configuration which includes filters for spam. We also used a Xenon 2 GHZ
4232 with a vanilla RedHat 8.0 sendmail configuration. Furthermore, we used
4233 qmail on a PIII-1000 running Sorcerer GNU Linux (SGL). The numbers for
4234 UDP and TCP are provided using the SGL configuration. The qmail benchmark
4235 uses qmail's internal filtering whereas the sendmail benchmarks relies on
4236 procmail to filter and deliver the mail. We used the transport layer to
4237 send a message of b bytes (excluding transport protocol headers) directly
4238 to the local machine. This way, network latency and packet loss on the
4239 wire have no impact on the timings. n messages were sent sequentially over
4240 the transport layer, sending message i+1 after the i-th message was
4241 received. All messages were sent over the same connection and the time to
4242 establish the connection was not taken into account since this overhead is
4243 minuscule in practice --- as long as a connection is used for a
4244 significant number of messages.
4246 @multitable @columnfractions .20 .15 .15 .15 .15 .15
4247 @headitem Transport @tab UDP @tab TCP @tab SMTP (Purdue sendmail)
4248 @tab SMTP (RH 8.0) @tab SMTP (SGL qmail)
4249 @item 11 bytes @tab 31 ms @tab 55 ms @tab 781 s @tab 77 s @tab 24 s
4250 @item 407 bytes @tab 37 ms @tab 62 ms @tab 789 s @tab 78 s @tab 25 s
4251 @item 1,221 bytes @tab 46 ms @tab 73 ms @tab 804 s @tab 78 s @tab 25 s
4254 The benchmarks show that UDP and TCP are, as expected, both significantly
4255 faster compared with any of the SMTP services. Among the SMTP
4256 implementations, there can be significant differences depending on the
4257 SMTP configuration. Filtering with an external tool like procmail that
4258 needs to re-parse its configuration for each mail can be very expensive.
4259 Applying spam filters can also significantly impact the performance of
4260 the underlying SMTP implementation. The microbenchmark shows that SMTP
4261 can be a viable solution for initiating peer-to-peer sessions: a couple of
4262 seconds to connect to a peer are probably not even going to be noticed by
4263 users. The next benchmark measures the possible throughput for a
4264 transport. Throughput can be measured by sending multiple messages in
4265 parallel and measuring packet loss. Note that not only UDP but also the
4266 TCP transport can actually loose messages since the TCP implementation
4267 drops messages if the @code{write} to the socket would block. While the
4268 SMTP protocol never drops messages itself, it is often so
4269 slow that only a fraction of the messages can be sent and received in the
4270 given time-bounds. For this benchmark we report the message loss after
4271 allowing t time for sending m messages. If messages were not sent (or
4272 received) after an overall timeout of t, they were considered lost. The
4273 benchmark was performed using two Xeon 2 GHZ machines running RedHat 8.0
4274 with sendmail. The machines were connected with a direct 100 MBit Ethernet
4275 connection.@ Figures udp1200, tcp1200 and smtp-MTUs show that the
4276 throughput for messages of size 1,200 octets is 2,343 kbps, 3,310 kbps
4277 and 6 kbps for UDP, TCP and SMTP respectively. The high per-message
4278 overhead of SMTP can be improved by increasing the MTU, for example, an
4279 MTU of 12,000 octets improves the throughput to 13 kbps as figure
4280 smtp-MTUs shows. Our research paper) has some more details on the
4281 benchmarking results.
4283 @cindex Bluetooth plugin
4284 @node Bluetooth plugin
4285 @section Bluetooth plugin
4288 This page describes the new Bluetooth transport plugin for GNUnet. The
4289 plugin is still in the testing stage so don't expect it to work
4290 perfectly. If you have any questions or problems just post them here or
4291 ask on the IRC channel.
4294 @item What do I need to use the Bluetooth plugin transport?
4295 @item BluetoothHow does it work?
4296 @item What possible errors should I be aware of?
4297 @item How do I configure my peer?
4298 @item How can I test it?
4302 * What do I need to use the Bluetooth plugin transport?::
4303 * How does it work2?::
4304 * What possible errors should I be aware of?::
4305 * How do I configure my peer2?::
4306 * How can I test it?::
4307 * The implementation of the Bluetooth transport plugin::
4310 @node What do I need to use the Bluetooth plugin transport?
4311 @subsection What do I need to use the Bluetooth plugin transport?
4314 If you are a GNU/Linux user and you want to use the Bluetooth
4315 transport plugin you should install the
4316 @command{BlueZ development libraries} (if they aren't already
4318 For instructions about how to install the libraries you should
4319 check out the BlueZ site
4320 (@uref{http://www.bluez.org/, http://www.bluez.org}). If you don't know if
4321 you have the necessary libraries, don't worry, just run the GNUnet
4322 configure script and you will be able to see a notification at the end
4323 which will warn you if you don't have the necessary libraries.
4325 If you are a Windows user you should have installed the
4326 @emph{MinGW}/@emph{MSys2} with the latest updates (especially the
4327 @emph{ws2bth} header). If this is your first build of GNUnet on Windows
4328 you should check out the SBuild repository. It will semi-automatically
4329 assembles a @emph{MinGW}/@emph{MSys2} installation with a lot of extra
4330 packages which are needed for the GNUnet build. So this will ease your
4331 work!@ Finally you just have to be sure that you have the correct drivers
4332 for your Bluetooth device installed and that your device is on and in a
4333 discoverable mode. The Windows Bluetooth Stack supports only the RFCOMM
4334 protocol so we cannot turn on your device programatically!
4336 @c FIXME: Change to unique title
4337 @node How does it work2?
4338 @subsection How does it work2?
4341 The Bluetooth transport plugin uses virtually the same code as the WLAN
4342 plugin and only the helper binary is different. The helper takes a single
4343 argument, which represents the interface name and is specified in the
4344 configuration file. Here are the basic steps that are followed by the
4345 helper binary used on GNU/Linux:
4348 @item it verifies if the name corresponds to a Bluetooth interface name
4349 @item it verifies if the interface is up (if it is not, it tries to bring
4351 @item it tries to enable the page and inquiry scan in order to make the
4352 device discoverable and to accept incoming connection requests
4353 @emph{The above operations require root access so you should start the
4354 transport plugin with root privileges.}
4355 @item it finds an available port number and registers a SDP service which
4356 will be used to find out on which port number is the server listening on
4357 and switch the socket in listening mode
4358 @item it sends a HELLO message with its address
4359 @item finally it forwards traffic from the reading sockets to the STDOUT
4360 and from the STDIN to the writing socket
4363 Once in a while the device will make an inquiry scan to discover the
4364 nearby devices and it will send them randomly HELLO messages for peer
4367 @node What possible errors should I be aware of?
4368 @subsection What possible errors should I be aware of?
4371 @emph{This section is dedicated for GNU/Linux users}
4373 Well there are many ways in which things could go wrong but I will try to
4374 present some tools that you could use to debug and some scenarios.
4378 @item @code{bluetoothd -n -d} : use this command to enable logging in the
4379 foreground and to print the logging messages
4381 @item @code{hciconfig}: can be used to configure the Bluetooth devices.
4382 If you run it without any arguments it will print information about the
4383 state of the interfaces. So if you receive an error that the device
4384 couldn't be brought up you should try to bring it manually and to see if
4385 it works (use @code{hciconfig -a hciX up}). If you can't and the
4386 Bluetooth address has the form 00:00:00:00:00:00 it means that there is
4387 something wrong with the D-Bus daemon or with the Bluetooth daemon. Use
4388 @code{bluetoothd} tool to see the logs
4390 @item @code{sdptool} can be used to control and interrogate SDP servers.
4391 If you encounter problems regarding the SDP server (like the SDP server is
4392 down) you should check out if the D-Bus daemon is running correctly and to
4393 see if the Bluetooth daemon started correctly(use @code{bluetoothd} tool).
4394 Also, sometimes the SDP service could work but somehow the device couldn't
4395 register its service. Use @code{sdptool browse [dev-address]} to see if
4396 the service is registered. There should be a service with the name of the
4397 interface and GNUnet as provider.
4399 @item @code{hcitool} : another useful tool which can be used to configure
4400 the device and to send some particular commands to it.
4402 @item @code{hcidump} : could be used for low level debugging
4405 @c FIXME: A more unique name
4406 @node How do I configure my peer2?
4407 @subsection How do I configure my peer2?
4410 On GNU/Linux, you just have to be sure that the interface name
4411 corresponds to the one that you want to use.
4412 Use the @code{hciconfig} tool to check that.
4413 By default it is set to hci0 but you can change it.
4415 A basic configuration looks like this:
4418 [transport-bluetooth]
4419 # Name of the interface (typically hciX)
4421 # Real hardware, no testing
4422 TESTMODE = 0 TESTING_IGNORE_KEYS = ACCEPT_FROM;
4425 In order to use the Bluetooth transport plugin when the transport service
4426 is started, you must add the plugin name to the default transport service
4427 plugins list. For example:
4430 [transport] ... PLUGINS = dns bluetooth ...
4433 If you want to use only the Bluetooth plugin set
4434 @emph{PLUGINS = bluetooth}
4436 On Windows, you cannot specify which device to use. The only thing that
4437 you should do is to add @emph{bluetooth} on the plugins list of the
4440 @node How can I test it?
4441 @subsection How can I test it?
4444 If you have two Bluetooth devices on the same machine and you are using
4449 @item create two different file configuration (one which will use the
4450 first interface (@emph{hci0}) and the other which will use the second
4451 interface (@emph{hci1})). Let's name them @emph{peer1.conf} and
4454 @item run @emph{gnunet-peerinfo -c peerX.conf -s} in order to generate the
4455 peers private keys. The @strong{X} must be replace with 1 or 2.
4457 @item run @emph{gnunet-arm -c peerX.conf -s -i=transport} in order to
4458 start the transport service. (Make sure that you have "bluetooth" on the
4459 transport plugins list if the Bluetooth transport service doesn't start.)
4461 @item run @emph{gnunet-peerinfo -c peer1.conf -s} to get the first peer's
4462 ID. If you already know your peer ID (you saved it from the first
4463 command), this can be skipped.
4465 @item run @emph{gnunet-transport -c peer2.conf -p=PEER1_ID -s} to start
4466 sending data for benchmarking to the other peer.
4471 This scenario will try to connect the second peer to the first one and
4472 then start sending data for benchmarking.
4474 On Windows you cannot test the plugin functionality using two Bluetooth
4475 devices from the same machine because after you install the drivers there
4476 will occur some conflicts between the Bluetooth stacks. (At least that is
4477 what happened on my machine : I wasn't able to use the Bluesoleil stack and
4478 the WINDCOMM one in the same time).
4480 If you have two different machines and your configuration files are good
4481 you can use the same scenario presented on the beginning of this section.
4483 Another way to test the plugin functionality is to create your own
4484 application which will use the GNUnet framework with the Bluetooth
4487 @node The implementation of the Bluetooth transport plugin
4488 @subsection The implementation of the Bluetooth transport plugin
4491 This page describes the implementation of the Bluetooth transport plugin.
4493 First I want to remind you that the Bluetooth transport plugin uses
4494 virtually the same code as the WLAN plugin and only the helper binary is
4495 different. Also the scope of the helper binary from the Bluetooth
4496 transport plugin is the same as the one used for the WLAN transport
4497 plugin: it accesses the interface and then it forwards traffic in both
4498 directions between the Bluetooth interface and stdin/stdout of the
4501 The Bluetooth plugin transport could be used both on GNU/Linux and Windows
4505 @item Linux functionality
4506 @item Windows functionality
4507 @item Pending Features
4513 * Linux functionality::
4514 * THE INITIALIZATION::
4516 * Details about the broadcast implementation::
4517 * Windows functionality::
4518 * Pending features::
4521 @node Linux functionality
4522 @subsubsection Linux functionality
4525 In order to implement the plugin functionality on GNU/Linux I
4526 used the BlueZ stack.
4527 For the communication with the other devices I used the RFCOMM
4528 protocol. Also I used the HCI protocol to gain some control over the
4529 device. The helper binary takes a single argument (the name of the
4530 Bluetooth interface) and is separated in two stages:
4532 @c %** 'THE INITIALIZATION' should be in bigger letters or stand out, not
4533 @c %** starting a new section?
4534 @node THE INITIALIZATION
4535 @subsubsection THE INITIALIZATION
4538 @item first, it checks if we have root privileges
4539 (@emph{Remember that we need to have root privileges in order to be able
4540 to bring the interface up if it is down or to change its state.}).
4542 @item second, it verifies if the interface with the given name exists.
4544 @strong{If the interface with that name exists and it is a Bluetooth
4547 @item it creates a RFCOMM socket which will be used for listening and call
4548 the @emph{open_device} method
4550 On the @emph{open_device} method:
4552 @item creates a HCI socket used to send control events to the the device
4553 @item searches for the device ID using the interface name
4554 @item saves the device MAC address
4555 @item checks if the interface is down and tries to bring it UP
4556 @item checks if the interface is in discoverable mode and tries to make it
4558 @item closes the HCI socket and binds the RFCOMM one
4559 @item switches the RFCOMM socket in listening mode
4560 @item registers the SDP service (the service will be used by the other
4561 devices to get the port on which this device is listening on)
4564 @item drops the root privileges
4566 @strong{If the interface is not a Bluetooth interface the helper exits
4567 with a suitable error}
4570 @c %** Same as for @node entry above
4572 @subsubsection THE LOOP
4574 The helper binary uses a list where it saves all the connected neighbour
4575 devices (@emph{neighbours.devices}) and two buffers (@emph{write_pout} and
4576 @emph{write_std}). The first message which is send is a control message
4577 with the device's MAC address in order to announce the peer presence to
4578 the neighbours. Here are a short description of what happens in the main
4582 @item Every time when it receives something from the STDIN it processes
4583 the data and saves the message in the first buffer (@emph{write_pout}).
4584 When it has something in the buffer, it gets the destination address from
4585 the buffer, searches the destination address in the list (if there is no
4586 connection with that device, it creates a new one and saves it to the
4587 list) and sends the message.
4588 @item Every time when it receives something on the listening socket it
4589 accepts the connection and saves the socket on a list with the reading
4590 sockets. @item Every time when it receives something from a reading
4591 socket it parses the message, verifies the CRC and saves it in the
4592 @emph{write_std} buffer in order to be sent later to the STDOUT.
4595 So in the main loop we use the select function to wait until one of the
4596 file descriptor saved in one of the two file descriptors sets used is
4597 ready to use. The first set (@emph{rfds}) represents the reading set and
4598 it could contain the list with the reading sockets, the STDIN file
4599 descriptor or the listening socket. The second set (@emph{wfds}) is the
4600 writing set and it could contain the sending socket or the STDOUT file
4601 descriptor. After the select function returns, we check which file
4602 descriptor is ready to use and we do what is supposed to do on that kind
4603 of event. @emph{For example:} if it is the listening socket then we
4604 accept a new connection and save the socket in the reading list; if it is
4605 the STDOUT file descriptor, then we write to STDOUT the message from the
4606 @emph{write_std} buffer.
4608 To find out on which port a device is listening on we connect to the local
4609 SDP server and search the registered service for that device.
4611 @emph{You should be aware of the fact that if the device fails to connect
4612 to another one when trying to send a message it will attempt one more
4613 time. If it fails again, then it skips the message.}
4614 @emph{Also you should know that the transport Bluetooth plugin has
4615 support for @strong{broadcast messages}.}
4617 @node Details about the broadcast implementation
4618 @subsubsection Details about the broadcast implementation
4621 First I want to point out that the broadcast functionality for the CONTROL
4622 messages is not implemented in a conventional way. Since the inquiry scan
4623 time is too big and it will take some time to send a message to all the
4624 discoverable devices I decided to tackle the problem in a different way.
4625 Here is how I did it:
4628 @item If it is the first time when I have to broadcast a message I make an
4629 inquiry scan and save all the devices' addresses to a vector.
4630 @item After the inquiry scan ends I take the first address from the list
4631 and I try to connect to it. If it fails, I try to connect to the next one.
4632 If it succeeds, I save the socket to a list and send the message to the
4634 @item When I have to broadcast another message, first I search on the list
4635 for a new device which I'm not connected to. If there is no new device on
4636 the list I go to the beginning of the list and send the message to the
4637 old devices. After 5 cycles I make a new inquiry scan to check out if
4638 there are new discoverable devices and save them to the list. If there
4639 are no new discoverable devices I reset the cycling counter and go again
4640 through the old list and send messages to the devices saved in it.
4646 @item every time when I have a broadcast message I look up on the list
4647 for a new device and send the message to it
4648 @item if I reached the end of the list for 5 times and I'm connected to
4649 all the devices from the list I make a new inquiry scan.
4650 @emph{The number of the list's cycles after an inquiry scan could be
4651 increased by redefining the MAX_LOOPS variable}
4652 @item when there are no new devices I send messages to the old ones.
4655 Doing so, the broadcast control messages will reach the devices but with
4658 @emph{NOTICE:} When I have to send a message to a certain device first I
4659 check on the broadcast list to see if we are connected to that device. If
4660 not we try to connect to it and in case of success we save the address and
4661 the socket on the list. If we are already connected to that device we
4662 simply use the socket.
4664 @node Windows functionality
4665 @subsubsection Windows functionality
4668 For Windows I decided to use the Microsoft Bluetooth stack which has the
4669 advantage of coming standard from Windows XP SP2. The main disadvantage is
4670 that it only supports the RFCOMM protocol so we will not be able to have
4671 a low level control over the Bluetooth device. Therefore it is the user
4672 responsibility to check if the device is up and in the discoverable mode.
4673 Also there are no tools which could be used for debugging in order to read
4674 the data coming from and going to a Bluetooth device, which obviously
4675 hindered my work. Another thing that slowed down the implementation of the
4676 plugin (besides that I wasn't too accommodated with the win32 API) was that
4677 there were some bugs on MinGW regarding the Bluetooth. Now they are solved
4678 but you should keep in mind that you should have the latest updates
4679 (especially the @emph{ws2bth} header).
4681 Besides the fact that it uses the Windows Sockets, the Windows
4682 implementation follows the same principles as the GNU/Linux one:
4685 @item It has a initalization part where it initializes the
4686 Windows Sockets, creates a RFCOMM socket which will be binded and switched
4687 to the listening mode and registers a SDP service. In the Microsoft
4688 Bluetooth API there are two ways to work with the SDP:
4690 @item an easy way which works with very simple service records
4691 @item a hard way which is useful when you need to update or to delete the
4696 Since I only needed the SDP service to find out on which port the device
4697 is listening on and that did not change, I decided to use the easy way.
4698 In order to register the service I used the @emph{WSASetService} function
4699 and I generated the @emph{Universally Unique Identifier} with the
4700 @emph{guidgen.exe} Windows's tool.
4702 In the loop section the only difference from the GNU/Linux implementation
4703 is that I used the @code{GNUNET_NETWORK} library for
4704 functions like @emph{accept}, @emph{bind}, @emph{connect} or
4705 @emph{select}. I decided to use the
4706 @code{GNUNET_NETWORK} library because I also needed to interact
4707 with the STDIN and STDOUT handles and on Windows
4708 the select function is only defined for sockets,
4709 and it will not work for arbitrary file handles.
4711 Another difference between GNU/Linux and Windows implementation is that in
4712 GNU/Linux, the Bluetooth address is represented in 48 bits
4713 while in Windows is represented in 64 bits.
4714 Therefore I had to do some changes on @emph{plugin_transport_wlan} header.
4716 Also, currently on Windows the Bluetooth plugin doesn't have support for
4717 broadcast messages. When it receives a broadcast message it will skip it.
4719 @node Pending features
4720 @subsubsection Pending features
4724 @item Implement the broadcast functionality on Windows @emph{(currently
4726 @item Implement a testcase for the helper :@ @emph{The testcase
4727 consists of a program which emulates the plugin and uses the helper. It
4728 will simulate connections, disconnections and data transfers.}
4731 If you have a new idea about a feature of the plugin or suggestions about
4732 how I could improve the implementation you are welcome to comment or to
4736 @section WLAN plugin
4739 This section documents how the wlan transport plugin works. Parts which
4740 are not implemented yet or could be better implemented are described at
4743 @cindex ATS Subsystem
4745 @section ATS Subsystem
4748 ATS stands for "automatic transport selection", and the function of ATS in
4749 GNUnet is to decide on which address (and thus transport plugin) should
4750 be used for two peers to communicate, and what bandwidth limits should be
4751 imposed on such an individual connection. To help ATS make an informed
4752 decision, higher-level services inform the ATS service about their
4753 requirements and the quality of the service rendered. The ATS service
4754 also interacts with the transport service to be appraised of working
4755 addresses and to communicate its resource allocation decisions. Finally,
4756 the ATS service's operation can be observed using a monitoring API.
4758 The main logic of the ATS service only collects the available addresses,
4759 their performance characteristics and the applications requirements, but
4760 does not make the actual allocation decision. This last critical step is
4761 left to an ATS plugin, as we have implemented (currently three) different
4762 allocation strategies which differ significantly in their performance and
4763 maturity, and it is still unclear if any particular plugin is generally
4766 @cindex CORE Subsystem
4767 @node CORE Subsystem
4768 @section CORE Subsystem
4771 The CORE subsystem in GNUnet is responsible for securing link-layer
4772 communications between nodes in the GNUnet overlay network. CORE builds
4773 on the TRANSPORT subsystem which provides for the actual, insecure,
4774 unreliable link-layer communication (for example, via UDP or WLAN), and
4775 then adds fundamental security to the connections:
4778 @item confidentiality with so-called perfect forward secrecy; we use
4780 (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman})
4781 powered by Curve25519
4782 (@uref{http://cr.yp.to/ecdh.html, Curve25519}) for the key
4783 exchange and then use symmetric encryption, encrypting with both AES-256
4784 (@uref{http://en.wikipedia.org/wiki/Rijndael, AES-256}) and
4785 Twofish (@uref{http://en.wikipedia.org/wiki/Twofish, Twofish})
4786 @item @uref{http://en.wikipedia.org/wiki/Authentication, authentication}
4787 is achieved by signing the ephemeral keys using Ed25519
4788 (@uref{http://ed25519.cr.yp.to/, Ed25519}), a deterministic
4790 (@uref{http://en.wikipedia.org/wiki/ECDSA, ECDSA})
4791 @item integrity protection (using SHA-512
4792 (@uref{http://en.wikipedia.org/wiki/SHA-2, SHA-512}) to do
4794 (@uref{http://en.wikipedia.org/wiki/Authenticated_encryption, encrypt-then-MAC}))
4796 (@uref{http://en.wikipedia.org/wiki/Replay_attack, replay})
4797 protection (using nonces, timestamps, challenge-response,
4798 message counters and ephemeral keys)
4799 @item liveness (keep-alive messages, timeout)
4804 * When is a peer "connected"?::
4806 * The CORE Client-Service Protocol::
4807 * The CORE Peer-to-Peer Protocol::
4810 @cindex core subsystem limitations
4812 @subsection Limitations
4815 CORE does not perform
4816 @uref{http://en.wikipedia.org/wiki/Routing, routing}; using CORE it is
4817 only possible to communicate with peers that happen to already be
4818 "directly" connected with each other. CORE also does not have an
4819 API to allow applications to establish such "direct" connections --- for
4820 this, applications can ask TRANSPORT, but TRANSPORT might not be able to
4821 establish a "direct" connection. The TOPOLOGY subsystem is responsible for
4822 trying to keep a few "direct" connections open at all times. Applications
4823 that need to talk to particular peers should use the CADET subsystem, as
4824 it can establish arbitrary "indirect" connections.
4826 Because CORE does not perform routing, CORE must only be used directly by
4827 applications that either perform their own routing logic (such as
4828 anonymous file-sharing) or that do not require routing, for example
4829 because they are based on flooding the network. CORE communication is
4830 unreliable and delivery is possibly out-of-order. Applications that
4831 require reliable communication should use the CADET service. Each
4832 application can only queue one message per target peer with the CORE
4833 service at any time; messages cannot be larger than approximately
4834 63 kilobytes. If messages are small, CORE may group multiple messages
4835 (possibly from different applications) prior to encryption. If permitted
4836 by the application (using the @uref{http://baus.net/on-tcp_cork/, cork}
4837 option), CORE may delay transmissions to facilitate grouping of multiple
4838 small messages. If cork is not enabled, CORE will transmit the message as
4839 soon as TRANSPORT allows it (TRANSPORT is responsible for limiting
4840 bandwidth and congestion control). CORE does not allow flow control;
4841 applications are expected to process messages at line-speed. If flow
4842 control is needed, applications should use the CADET service.
4844 @cindex when is a peer connected
4845 @node When is a peer "connected"?
4846 @subsection When is a peer "connected"?
4849 In addition to the security features mentioned above, CORE also provides
4850 one additional key feature to applications using it, and that is a
4851 limited form of protocol-compatibility checking. CORE distinguishes
4852 between TRANSPORT-level connections (which enable communication with other
4853 peers) and application-level connections. Applications using the CORE API
4854 will (typically) learn about application-level connections from CORE, and
4855 not about TRANSPORT-level connections. When a typical application uses
4856 CORE, it will specify a set of message types
4857 (from @code{gnunet_protocols.h}) that it understands. CORE will then
4858 notify the application about connections it has with other peers if and
4859 only if those applications registered an intersecting set of message
4860 types with their CORE service. Thus, it is quite possible that CORE only
4861 exposes a subset of the established direct connections to a particular
4862 application --- and different applications running above CORE might see
4863 different sets of connections at the same time.
4865 A special case are applications that do not register a handler for any
4867 CORE assumes that these applications merely want to monitor connections
4868 (or "all" messages via other callbacks) and will notify those applications
4869 about all connections. This is used, for example, by the
4870 @code{gnunet-core} command-line tool to display the active connections.
4871 Note that it is also possible that the TRANSPORT service has more active
4872 connections than the CORE service, as the CORE service first has to
4873 perform a key exchange with connecting peers before exchanging information
4874 about supported message types and notifying applications about the new
4877 @cindex libgnunetcore
4879 @subsection libgnunetcore
4882 The CORE API (defined in @file{gnunet_core_service.h}) is the basic
4883 messaging API used by P2P applications built using GNUnet. It provides
4884 applications the ability to send and receive encrypted messages to the
4885 peer's "directly" connected neighbours.
4887 As CORE connections are generally "direct" connections,@ applications must
4888 not assume that they can connect to arbitrary peers this way, as "direct"
4889 connections may not always be possible. Applications using CORE are
4890 notified about which peers are connected. Creating new "direct"
4891 connections must be done using the TRANSPORT API.
4893 The CORE API provides unreliable, out-of-order delivery. While the
4894 implementation tries to ensure timely, in-order delivery, both message
4895 losses and reordering are not detected and must be tolerated by the
4896 application. Most important, the core will NOT perform retransmission if
4897 messages could not be delivered.
4899 Note that CORE allows applications to queue one message per connected
4900 peer. The rate at which each connection operates is influenced by the
4901 preferences expressed by local application as well as restrictions
4902 imposed by the other peer. Local applications can express their
4903 preferences for particular connections using the "performance" API of the
4906 Applications that require more sophisticated transmission capabilities
4907 such as TCP-like behavior, or if you intend to send messages to arbitrary
4908 remote peers, should use the CADET API.
4910 The typical use of the CORE API is to connect to the CORE service using
4911 @code{GNUNET_CORE_connect}, process events from the CORE service (such as
4912 peers connecting, peers disconnecting and incoming messages) and send
4913 messages to connected peers using
4914 @code{GNUNET_CORE_notify_transmit_ready}. Note that applications must
4915 cancel pending transmission requests if they receive a disconnect event
4916 for a peer that had a transmission pending; furthermore, queuing more
4917 than one transmission request per peer per application using the
4918 service is not permitted.
4920 The CORE API also allows applications to monitor all communications of the
4921 peer prior to encryption (for outgoing messages) or after decryption (for
4922 incoming messages). This can be useful for debugging, diagnostics or to
4923 establish the presence of cover traffic (for anonymity). As monitoring
4924 applications are often not interested in the payload, the monitoring
4925 callbacks can be configured to only provide the message headers (including
4926 the message type and size) instead of copying the full data stream to the
4929 The init callback of the @code{GNUNET_CORE_connect} function is called
4930 with the hash of the public key of the peer. This public key is used to
4931 identify the peer globally in the GNUnet network. Applications are
4932 encouraged to check that the provided hash matches the hash that they are
4933 using (as theoretically the application may be using a different
4934 configuration file with a different private key, which would result in
4937 As with most service APIs, the CORE API isolates applications from crashes
4938 of the CORE service. If the CORE service crashes, the application will see
4939 disconnect events for all existing connections. Once the connections are
4940 re-established, the applications will be receive matching connect events.
4942 @cindex core clinet-service protocol
4943 @node The CORE Client-Service Protocol
4944 @subsection The CORE Client-Service Protocol
4947 This section describes the protocol between an application using the CORE
4948 service (the client) and the CORE service process itself.
4958 @subsubsection Setup2
4961 When a client connects to the CORE service, it first sends a
4962 @code{InitMessage} which specifies options for the connection and a set of
4963 message type values which are supported by the application. The options
4964 bitmask specifies which events the client would like to be notified about.
4965 The options include:
4968 @item GNUNET_CORE_OPTION_NOTHING No notifications
4969 @item GNUNET_CORE_OPTION_STATUS_CHANGE Peers connecting and disconnecting
4970 @item GNUNET_CORE_OPTION_FULL_INBOUND All inbound messages (after
4971 decryption) with full payload
4972 @item GNUNET_CORE_OPTION_HDR_INBOUND Just the @code{MessageHeader}
4973 of all inbound messages
4974 @item GNUNET_CORE_OPTION_FULL_OUTBOUND All outbound
4975 messages (prior to encryption) with full payload
4976 @item GNUNET_CORE_OPTION_HDR_OUTBOUND Just the @code{MessageHeader} of all
4980 Typical applications will only monitor for connection status changes.
4982 The CORE service responds to the @code{InitMessage} with an
4983 @code{InitReplyMessage} which contains the peer's identity. Afterwards,
4984 both CORE and the client can send messages.
4987 @subsubsection Notifications
4990 The CORE will send @code{ConnectNotifyMessage}s and
4991 @code{DisconnectNotifyMessage}s whenever peers connect or disconnect from
4992 the CORE (assuming their type maps overlap with the message types
4993 registered by the client). When the CORE receives a message that matches
4994 the set of message types specified during the @code{InitMessage} (or if
4995 monitoring is enabled in for inbound messages in the options), it sends a
4996 @code{NotifyTrafficMessage} with the peer identity of the sender and the
4997 decrypted payload. The same message format (except with
4998 @code{GNUNET_MESSAGE_TYPE_CORE_NOTIFY_OUTBOUND} for the message type) is
4999 used to notify clients monitoring outbound messages; here, the peer
5000 identity given is that of the receiver.
5003 @subsubsection Sending
5006 When a client wants to transmit a message, it first requests a
5007 transmission slot by sending a @code{SendMessageRequest} which specifies
5008 the priority, deadline and size of the message. Note that these values
5009 may be ignored by CORE. When CORE is ready for the message, it answers
5010 with a @code{SendMessageReady} response. The client can then transmit the
5011 payload with a @code{SendMessage} message. Note that the actual message
5012 size in the @code{SendMessage} is allowed to be smaller than the size in
5013 the original request. A client may at any time send a fresh
5014 @code{SendMessageRequest}, which then superceeds the previous
5015 @code{SendMessageRequest}, which is then no longer valid. The client can
5016 tell which @code{SendMessageRequest} the CORE service's
5017 @code{SendMessageReady} message is for as all of these messages contain a
5018 "unique" request ID (based on a counter incremented by the client
5021 @cindex CORE Peer-to-Peer Protocol
5022 @node The CORE Peer-to-Peer Protocol
5023 @subsection The CORE Peer-to-Peer Protocol
5028 * Creating the EphemeralKeyMessage::
5029 * Establishing a connection::
5030 * Encryption and Decryption::
5034 @cindex EphemeralKeyMessage creation
5035 @node Creating the EphemeralKeyMessage
5036 @subsubsection Creating the EphemeralKeyMessage
5039 When the CORE service starts, each peer creates a fresh ephemeral (ECC)
5040 public-private key pair and signs the corresponding
5041 @code{EphemeralKeyMessage} with its long-term key (which we usually call
5042 the peer's identity; the hash of the public long term key is what results
5043 in a @code{struct GNUNET_PeerIdentity} in all GNUnet APIs. The ephemeral
5044 key is ONLY used for an ECDHE
5045 (@uref{http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman, Elliptic-curve Diffie---Hellman})
5046 exchange by the CORE service to establish symmetric session keys. A peer
5047 will use the same @code{EphemeralKeyMessage} for all peers for
5048 @code{REKEY_FREQUENCY}, which is usually 12 hours. After that time, it
5049 will create a fresh ephemeral key (forgetting the old one) and broadcast
5050 the new @code{EphemeralKeyMessage} to all connected peers, resulting in
5051 fresh symmetric session keys. Note that peers independently decide on
5052 when to discard ephemeral keys; it is not a protocol violation to discard
5053 keys more often. Ephemeral keys are also never stored to disk; restarting
5054 a peer will thus always create a fresh ephemeral key. The use of ephemeral
5055 keys is what provides @uref{http://en.wikipedia.org/wiki/Forward_secrecy, forward secrecy}.
5057 Just before transmission, the @code{EphemeralKeyMessage} is patched to
5058 reflect the current sender_status, which specifies the current state of
5059 the connection from the point of view of the sender. The possible values
5063 @item @code{KX_STATE_DOWN} Initial value, never used on the network
5064 @item @code{KX_STATE_KEY_SENT} We sent our ephemeral key, do not know the
5065 key of the other peer
5066 @item @code{KX_STATE_KEY_RECEIVED} This peer has received a valid
5067 ephemeral key of the other peer, but we are waiting for the other peer to
5068 confirm it's authenticity (ability to decode) via challenge-response.
5069 @item @code{KX_STATE_UP} The connection is fully up from the point of
5070 view of the sender (now performing keep-alives)
5071 @item @code{KX_STATE_REKEY_SENT} The sender has initiated a rekeying
5072 operation; the other peer has so far failed to confirm a working
5073 connection using the new ephemeral key
5076 @node Establishing a connection
5077 @subsubsection Establishing a connection
5080 Peers begin their interaction by sending a @code{EphemeralKeyMessage} to
5081 the other peer once the TRANSPORT service notifies the CORE service about
5083 A peer receiving an @code{EphemeralKeyMessage} with a status
5084 indicating that the sender does not have the receiver's ephemeral key, the
5085 receiver's @code{EphemeralKeyMessage} is sent in response.
5086 Additionally, if the receiver has not yet confirmed the authenticity of
5087 the sender, it also sends an (encrypted)@code{PingMessage} with a
5088 challenge (and the identity of the target) to the other peer. Peers
5089 receiving a @code{PingMessage} respond with an (encrypted)
5090 @code{PongMessage} which includes the challenge. Peers receiving a
5091 @code{PongMessage} check the challenge, and if it matches set the
5092 connection to @code{KX_STATE_UP}.
5094 @node Encryption and Decryption
5095 @subsubsection Encryption and Decryption
5098 All functions related to the key exchange and encryption/decryption of
5099 messages can be found in @file{gnunet-service-core_kx.c} (except for the
5100 cryptographic primitives, which are in @file{util/crypto*.c}).
5101 Given the key material from ECDHE, a Key derivation function
5102 (@uref{https://en.wikipedia.org/wiki/Key_derivation_function, Key derivation function})
5103 is used to derive two pairs of encryption and decryption keys for AES-256
5104 and TwoFish, as well as initialization vectors and authentication keys
5106 (@uref{https://en.wikipedia.org/wiki/HMAC, HMAC})).
5107 The HMAC is computed over the encrypted payload.
5108 Encrypted messages include an iv_seed and the HMAC in the header.
5110 Each encrypted message in the CORE service includes a sequence number and
5111 a timestamp in the encrypted payload. The CORE service remembers the
5112 largest observed sequence number and a bit-mask which represents which of
5113 the previous 32 sequence numbers were already used.
5114 Messages with sequence numbers lower than the largest observed sequence
5115 number minus 32 are discarded. Messages with a timestamp that is less
5116 than @code{REKEY_TOLERANCE} off (5 minutes) are also discarded. This of
5117 course means that system clocks need to be reasonably synchronized for
5118 peers to be able to communicate. Additionally, as the ephemeral key
5119 changes every 12 hours, a peer would not even be able to decrypt messages
5120 older than 12 hours.
5123 @subsubsection Type maps
5126 Once an encrypted connection has been established, peers begin to exchange
5127 type maps. Type maps are used to allow the CORE service to determine which
5128 (encrypted) connections should be shown to which applications. A type map
5129 is an array of 65536 bits representing the different types of messages
5130 understood by applications using the CORE service. Each CORE service
5131 maintains this map, simply by setting the respective bit for each message
5132 type supported by any of the applications using the CORE service. Note
5133 that bits for message types embedded in higher-level protocols (such as
5134 MESH) will not be included in these type maps.
5136 Typically, the type map of a peer will be sparse. Thus, the CORE service
5137 attempts to compress its type map using @code{gzip}-style compression
5138 ("deflate") prior to transmission. However, if the compression fails to
5139 compact the map, the map may also be transmitted without compression
5140 (resulting in @code{GNUNET_MESSAGE_TYPE_CORE_COMPRESSED_TYPE_MAP} or
5141 @code{GNUNET_MESSAGE_TYPE_CORE_BINARY_TYPE_MAP} messages respectively).
5142 Upon receiving a type map, the respective CORE service notifies
5143 applications about the connection to the other peer if they support any
5144 message type indicated in the type map (or no message type at all).
5145 If the CORE service experience a connect or disconnect event from an
5146 application, it updates its type map (setting or unsetting the respective
5147 bits) and notifies its neighbours about the change.
5148 The CORE services of the neighbours then in turn generate connect and
5149 disconnect events for the peer that sent the type map for their respective
5150 applications. As CORE messages may be lost, the CORE service confirms
5151 receiving a type map by sending back a
5152 @code{GNUNET_MESSAGE_TYPE_CORE_CONFIRM_TYPE_MAP}. If such a confirmation
5153 (with the correct hash of the type map) is not received, the sender will
5154 retransmit the type map (with exponential back-off).
5156 @cindex CADET Subsystem
5157 @node CADET Subsystem
5158 @section CADET Subsystem
5160 The CADET subsystem in GNUnet is responsible for secure end-to-end
5161 communications between nodes in the GNUnet overlay network. CADET builds
5162 on the CORE subsystem which provides for the link-layer communication and
5163 then adds routing, forwarding and additional security to the connections.
5164 CADET offers the same cryptographic services as CORE, but on an
5165 end-to-end level. This is done so peers retransmitting traffic on behalf
5166 of other peers cannot access the payload data.
5169 @item CADET provides confidentiality with so-called perfect forward
5170 secrecy; we use ECDHE powered by Curve25519 for the key exchange and then
5171 use symmetric encryption, encrypting with both AES-256 and Twofish
5172 @item authentication is achieved by signing the ephemeral keys using
5173 Ed25519, a deterministic variant of ECDSA
5174 @item integrity protection (using SHA-512 to do encrypt-then-MAC, although
5175 only 256 bits are sent to reduce overhead)
5176 @item replay protection (using nonces, timestamps, challenge-response,
5177 message counters and ephemeral keys)
5178 @item liveness (keep-alive messages, timeout)
5181 Additional to the CORE-like security benefits, CADET offers other
5182 properties that make it a more universal service than CORE.
5185 @item CADET can establish channels to arbitrary peers in GNUnet. If a
5186 peer is not immediately reachable, CADET will find a path through the
5187 network and ask other peers to retransmit the traffic on its behalf.
5188 @item CADET offers (optional) reliability mechanisms. In a reliable
5189 channel traffic is guaranteed to arrive complete, unchanged and in-order.
5190 @item CADET takes care of flow and congestion control mechanisms, not
5191 allowing the sender to send more traffic than the receiver or the network
5192 are able to process.
5199 @cindex libgnunetcadet
5200 @node libgnunetcadet
5201 @subsection libgnunetcadet
5204 The CADET API (defined in @file{gnunet_cadet_service.h}) is the
5205 messaging API used by P2P applications built using GNUnet.
5206 It provides applications the ability to send and receive encrypted
5207 messages to any peer participating in GNUnet.
5208 The API is heavily base on the CORE API.
5210 CADET delivers messages to other peers in "channels".
5211 A channel is a permanent connection defined by a destination peer
5212 (identified by its public key) and a port number.
5213 Internally, CADET tunnels all channels towards a destination peer
5214 using one session key and relays the data on multiple "connections",
5215 independent from the channels.
5217 Each channel has optional parameters, the most important being the
5219 Should a message get lost on TRANSPORT/CORE level, if a channel is
5220 created with as reliable, CADET will retransmit the lost message and
5221 deliver it in order to the destination application.
5223 To communicate with other peers using CADET, it is necessary to first
5224 connect to the service using @code{GNUNET_CADET_connect}.
5225 This function takes several parameters in form of callbacks, to allow the
5226 client to react to various events, like incoming channels or channels that
5227 terminate, as well as specify a list of ports the client wishes to listen
5228 to (at the moment it is not possible to start listening on further ports
5229 once connected, but nothing prevents a client to connect several times to
5230 CADET, even do one connection per listening port).
5231 The function returns a handle which has to be used for any further
5232 interaction with the service.
5234 To connect to a remote peer a client has to call the
5235 @code{GNUNET_CADET_channel_create} function. The most important parameters
5236 given are the remote peer's identity (it public key) and a port, which
5237 specifies which application on the remote peer to connect to, similar to
5238 TCP/UDP ports. CADET will then find the peer in the GNUnet network and
5239 establish the proper low-level connections and do the necessary key
5240 exchanges to assure and authenticated, secure and verified communication.
5241 Similar to @code{GNUNET_CADET_connect},@code{GNUNET_CADET_create_channel}
5242 returns a handle to interact with the created channel.
5244 For every message the client wants to send to the remote application,
5245 @code{GNUNET_CADET_notify_transmit_ready} must be called, indicating the
5246 channel on which the message should be sent and the size of the message
5247 (but not the message itself!). Once CADET is ready to send the message,
5248 the provided callback will fire, and the message contents are provided to
5251 Please note the CADET does not provide an explicit notification of when a
5252 channel is connected. In loosely connected networks, like big wireless
5253 mesh networks, this can take several seconds, even minutes in the worst
5254 case. To be alerted when a channel is online, a client can call
5255 @code{GNUNET_CADET_notify_transmit_ready} immediately after
5256 @code{GNUNET_CADET_create_channel}. When the callback is activated, it
5257 means that the channel is online. The callback can give 0 bytes to CADET
5258 if no message is to be sent, this is OK.
5260 If a transmission was requested but before the callback fires it is no
5261 longer needed, it can be canceled with
5262 @code{GNUNET_CADET_notify_transmit_ready_cancel}, which uses the handle
5263 given back by @code{GNUNET_CADET_notify_transmit_ready}.
5264 As in the case of CORE, only one message can be requested at a time: a
5265 client must not call @code{GNUNET_CADET_notify_transmit_ready} again until
5266 the callback is called or the request is canceled.
5268 When a channel is no longer needed, a client can call
5269 @code{GNUNET_CADET_channel_destroy} to get rid of it.
5270 Note that CADET will try to transmit all pending traffic before notifying
5271 the remote peer of the destruction of the channel, including
5272 retransmitting lost messages if the channel was reliable.
5274 Incoming channels, channels being closed by the remote peer, and traffic
5275 on any incoming or outgoing channels are given to the client when CADET
5276 executes the callbacks given to it at the time of
5277 @code{GNUNET_CADET_connect}.
5279 Finally, when an application no longer wants to use CADET, it should call
5280 @code{GNUNET_CADET_disconnect}, but first all channels and pending
5281 transmissions must be closed (otherwise CADET will complain).
5283 @cindex NSE Subsystem
5285 @section NSE Subsystem
5288 NSE stands for @dfn{Network Size Estimation}. The NSE subsystem provides
5289 other subsystems and users with a rough estimate of the number of peers
5290 currently participating in the GNUnet overlay.
5291 The computed value is not a precise number as producing a precise number
5292 in a decentralized, efficient and secure way is impossible.
5293 While NSE's estimate is inherently imprecise, NSE also gives the expected
5294 range. For a peer that has been running in a stable network for a
5295 while, the real network size will typically (99.7% of the time) be in the
5296 range of [2/3 estimate, 3/2 estimate]. We will now give an overview of the
5297 algorithm used to calculate the estimate;
5298 all of the details can be found in this technical report.
5300 @c FIXME: link to the report.
5306 * The NSE Client-Service Protocol::
5307 * The NSE Peer-to-Peer Protocol::
5311 @subsection Motivation
5314 Some subsystems, like DHT, need to know the size of the GNUnet network to
5315 optimize some parameters of their own protocol. The decentralized nature
5316 of GNUnet makes efficient and securely counting the exact number of peers
5317 infeasible. Although there are several decentralized algorithms to count
5318 the number of peers in a system, so far there is none to do so securely.
5319 Other protocols may allow any malicious peer to manipulate the final
5320 result or to take advantage of the system to perform
5321 @dfn{Denial of Service} (DoS) attacks against the network.
5322 GNUnet's NSE protocol avoids these drawbacks.
5330 @cindex NSE security
5331 @cindex nse security
5333 @subsubsection Security
5336 The NSE subsystem is designed to be resilient against these attacks.
5337 It uses @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proofs of work}
5338 to prevent one peer from impersonating a large number of participants,
5339 which would otherwise allow an adversary to artificially inflate the
5341 The DoS protection comes from the time-based nature of the protocol:
5342 the estimates are calculated periodically and out-of-time traffic is
5343 either ignored or stored for later retransmission by benign peers.
5344 In particular, peers cannot trigger global network communication at will.
5346 @cindex NSE principle
5347 @cindex nse principle
5349 @subsection Principle
5352 The algorithm calculates the estimate by finding the globally closest
5353 peer ID to a random, time-based value.
5355 The idea is that the closer the ID is to the random value, the more
5356 "densely packed" the ID space is, and therefore, more peers are in the
5366 * Controlled Flooding::
5367 * Calculating the estimate::
5371 @subsubsection Example
5374 Suppose all peers have IDs between 0 and 100 (our ID space), and the
5376 If the closest peer has the ID 70 we can imagine that the average
5377 "distance" between peers is around 30 and therefore the are around 3
5378 peers in the whole ID space. On the other hand, if the closest peer has
5379 the ID 44, we can imagine that the space is rather packed with peers,
5380 maybe as much as 50 of them.
5381 Naturally, we could have been rather unlucky, and there is only one peer
5382 and happens to have the ID 44. Thus, the current estimate is calculated
5383 as the average over multiple rounds, and not just a single sample.
5386 @subsubsection Algorithm
5389 Given that example, one can imagine that the job of the subsystem is to
5390 efficiently communicate the ID of the closest peer to the target value
5391 to all the other peers, who will calculate the estimate from it.
5394 @subsubsection Target value
5398 The target value itself is generated by hashing the current time, rounded
5399 down to an agreed value. If the rounding amount is 1h (default) and the
5400 time is 12:34:56, the time to hash would be 12:00:00. The process is
5401 repeated each rounding amount (in this example would be every hour).
5402 Every repetition is called a round.
5405 @subsubsection Timing
5408 The NSE subsystem has some timing control to avoid everybody broadcasting
5409 its ID all at one. Once each peer has the target random value, it
5410 compares its own ID to the target and calculates the hypothetical size of
5411 the network if that peer were to be the closest.
5412 Then it compares the hypothetical size with the estimate from the previous
5413 rounds. For each value there is an associated point in the period,
5414 let's call it "broadcast time". If its own hypothetical estimate
5415 is the same as the previous global estimate, its "broadcast time" will be
5416 in the middle of the round. If its bigger it will be earlier and if its
5417 smaller (the most likely case) it will be later. This ensures that the
5418 peers closest to the target value start broadcasting their ID the first.
5420 @node Controlled Flooding
5421 @subsubsection Controlled Flooding
5425 When a peer receives a value, first it verifies that it is closer than the
5426 closest value it had so far, otherwise it answers the incoming message
5427 with a message containing the better value. Then it checks a proof of
5428 work that must be included in the incoming message, to ensure that the
5429 other peer's ID is not made up (otherwise a malicious peer could claim to
5430 have an ID of exactly the target value every round). Once validated, it
5431 compares the broadcast time of the received value with the current time
5432 and if it's not too early, sends the received value to its neighbors.
5433 Otherwise it stores the value until the correct broadcast time comes.
5434 This prevents unnecessary traffic of sub-optimal values, since a better
5435 value can come before the broadcast time, rendering the previous one
5436 obsolete and saving the traffic that would have been used to broadcast it
5439 @node Calculating the estimate
5440 @subsubsection Calculating the estimate
5444 Once the closest ID has been spread across the network each peer gets the
5445 exact distance between this ID and the target value of the round and
5446 calculates the estimate with a mathematical formula described in the tech
5447 report. The estimate generated with this method for a single round is not
5448 very precise. Remember the case of the example, where the only peer is the
5449 ID 44 and we happen to generate the target value 42, thinking there are
5450 50 peers in the network. Therefore, the NSE subsystem remembers the last
5451 64 estimates and calculates an average over them, giving a result of which
5452 usually has one bit of uncertainty (the real size could be half of the
5453 estimate or twice as much). Note that the actual network size is
5454 calculated in powers of two of the raw input, thus one bit of uncertainty
5455 means a factor of two in the size estimate.
5457 @cindex libgnunetnse
5459 @subsection libgnunetnse
5463 The NSE subsystem has the simplest API of all services, with only two
5464 calls: @code{GNUNET_NSE_connect} and @code{GNUNET_NSE_disconnect}.
5466 The connect call gets a callback function as a parameter and this function
5467 is called each time the network agrees on an estimate. This usually is
5468 once per round, with some exceptions: if the closest peer has a late
5469 local clock and starts spreading its ID after everyone else agreed on a
5470 value, the callback might be activated twice in a round, the second value
5471 being always bigger than the first. The default round time is set to
5474 The disconnect call disconnects from the NSE subsystem and the callback
5475 is no longer called with new estimates.
5481 * libgnunetnse - Examples::
5485 @subsubsection Results
5489 The callback provides two values: the average and the
5490 @uref{http://en.wikipedia.org/wiki/Standard_deviation, standard deviation}
5491 of the last 64 rounds. The values provided by the callback function are
5492 logarithmic, this means that the real estimate numbers can be obtained by
5493 calculating 2 to the power of the given value (2average). From a
5494 statistics point of view this means that:
5497 @item 68% of the time the real size is included in the interval
5498 [(2average-stddev), 2]
5499 @item 95% of the time the real size is included in the interval
5500 [(2average-2*stddev, 2^average+2*stddev]
5501 @item 99.7% of the time the real size is included in the interval
5502 [(2average-3*stddev, 2average+3*stddev]
5505 The expected standard variation for 64 rounds in a network of stable size
5506 is 0.2. Thus, we can say that normally:
5509 @item 68% of the time the real size is in the range [-13%, +15%]
5510 @item 95% of the time the real size is in the range [-24%, +32%]
5511 @item 99.7% of the time the real size is in the range [-34%, +52%]
5514 As said in the introduction, we can be quite sure that usually the real
5515 size is between one third and three times the estimate. This can of
5516 course vary with network conditions.
5517 Thus, applications may want to also consider the provided standard
5518 deviation value, not only the average (in particular, if the standard
5519 variation is very high, the average maybe meaningless: the network size is
5522 @node libgnunetnse - Examples
5523 @subsubsection libgnunetnse -Examples
5527 Let's close with a couple examples.
5531 @item Average: 10, std dev: 1 Here the estimate would be
5532 2^10 = 1024 peers. (The range in which we can be 95% sure is:
5533 [2^8, 2^12] = [256, 4096]. We can be very (>99.7%) sure that the network
5534 is not a hundred peers and absolutely sure that it is not a million peers,
5535 but somewhere around a thousand.)
5537 @item Average 22, std dev: 0.2 Here the estimate would be
5538 2^22 = 4 Million peers. (The range in which we can be 99.7% sure
5539 is: [2^21.4, 2^22.6] = [2.8M, 6.3M]. We can be sure that the network size
5540 is around four million, with absolutely way of it being 1 million.)
5544 To put this in perspective, if someone remembers the LHC Higgs boson
5545 results, were announced with "5 sigma" and "6 sigma" certainties. In this
5546 case a 5 sigma minimum would be 2 million and a 6 sigma minimum,
5549 @node The NSE Client-Service Protocol
5550 @subsection The NSE Client-Service Protocol
5554 As with the API, the client-service protocol is very simple, only has 2
5555 different messages, defined in @code{src/nse/nse.h}:
5558 @item @code{GNUNET_MESSAGE_TYPE_NSE_START}@ This message has no parameters
5559 and is sent from the client to the service upon connection.
5560 @item @code{GNUNET_MESSAGE_TYPE_NSE_ESTIMATE}@ This message is sent from
5561 the service to the client for every new estimate and upon connection.
5562 Contains a timestamp for the estimate, the average and the standard
5563 deviation for the respective round.
5566 When the @code{GNUNET_NSE_disconnect} API call is executed, the client
5567 simply disconnects from the service, with no message involved.
5569 @cindex NSE Peer-to-Peer Protocol
5570 @node The NSE Peer-to-Peer Protocol
5571 @subsection The NSE Peer-to-Peer Protocol
5575 The NSE subsystem only has one message in the P2P protocol, the
5576 @code{GNUNET_MESSAGE_TYPE_NSE_P2P_FLOOD} message.
5578 This message key contents are the timestamp to identify the round
5579 (differences in system clocks may cause some peers to send messages way
5580 too early or way too late, so the timestamp allows other peers to
5581 identify such messages easily), the
5582 @uref{http://en.wikipedia.org/wiki/Proof-of-work_system, proof of work}
5583 used to make it difficult to mount a
5584 @uref{http://en.wikipedia.org/wiki/Sybil_attack, Sybil attack}, and the
5585 public key, which is used to verify the signature on the message.
5587 Every peer stores a message for the previous, current and next round. The
5588 messages for the previous and current round are given to peers that
5589 connect to us. The message for the next round is simply stored until our
5590 system clock advances to the next round. The message for the current round
5591 is what we are flooding the network with right now.
5592 At the beginning of each round the peer does the following:
5595 @item calculates its own distance to the target value
5596 @item creates, signs and stores the message for the current round (unless
5597 it has a better message in the "next round" slot which came early in the
5599 @item calculates, based on the stored round message (own or received) when
5600 to start flooding it to its neighbors
5603 Upon receiving a message the peer checks the validity of the message
5604 (round, proof of work, signature). The next action depends on the
5605 contents of the incoming message:
5608 @item if the message is worse than the current stored message, the peer
5609 sends the current message back immediately, to stop the other peer from
5610 spreading suboptimal results
5611 @item if the message is better than the current stored message, the peer
5612 stores the new message and calculates the new target time to start
5613 spreading it to its neighbors (excluding the one the message came from)
5614 @item if the message is for the previous round, it is compared to the
5615 message stored in the "previous round slot", which may then be updated
5616 @item if the message is for the next round, it is compared to the message
5617 stored in the "next round slot", which again may then be updated
5620 Finally, when it comes to send the stored message for the current round to
5621 the neighbors there is a random delay added for each neighbor, to avoid
5622 traffic spikes and minimize cross-messages.
5624 @cindex HOSTLIST Subsystem
5625 @node HOSTLIST Subsystem
5626 @section HOSTLIST Subsystem
5630 Peers in the GNUnet overlay network need address information so that they
5631 can connect with other peers. GNUnet uses so called HELLO messages to
5632 store and exchange peer addresses.
5633 GNUnet provides several methods for peers to obtain this information:
5636 @item out-of-band exchange of HELLO messages (manually, using for example
5638 @item HELLO messages shipped with GNUnet (automatic with distribution)
5639 @item UDP neighbor discovery in LAN (IPv4 broadcast, IPv6 multicast)
5640 @item topology gossiping (learning from other peers we already connected
5642 @item the HOSTLIST daemon covered in this section, which is particularly
5643 relevant for bootstrapping new peers.
5646 New peers have no existing connections (and thus cannot learn from gossip
5647 among peers), may not have other peers in their LAN and might be started
5648 with an outdated set of HELLO messages from the distribution.
5649 In this case, getting new peers to connect to the network requires either
5650 manual effort or the use of a HOSTLIST to obtain HELLOs.
5654 * Overview for the HOSTLIST subsystem::
5655 * Interacting with the HOSTLIST daemon::
5656 * Hostlist security address validation::
5657 * The HOSTLIST daemon::
5658 * The HOSTLIST server::
5659 * The HOSTLIST client::
5668 The basic information peers require to connect to other peers are
5669 contained in so called HELLO messages you can think of as a business card.
5670 Besides the identity of the peer (based on the cryptographic public key) a
5671 HELLO message may contain address information that specifies ways to
5672 contact a peer. By obtaining HELLO messages, a peer can learn how to
5673 contact other peers.
5675 @node Overview for the HOSTLIST subsystem
5676 @subsection Overview for the HOSTLIST subsystem
5680 The HOSTLIST subsystem provides a way to distribute and obtain contact
5681 information to connect to other peers using a simple HTTP GET request.
5682 It's implementation is split in three parts, the main file for the daemon
5683 itself (@file{gnunet-daemon-hostlist.c}), the HTTP client used to download
5684 peer information (@file{hostlist-client.c}) and the server component used
5685 to provide this information to other peers (@file{hostlist-server.c}).
5686 The server is basically a small HTTP web server (based on GNU
5687 libmicrohttpd) which provides a list of HELLOs known to the local peer for
5688 download. The client component is basically a HTTP client
5689 (based on libcurl) which can download hostlists from one or more websites.
5690 The hostlist format is a binary blob containing a sequence of HELLO
5691 messages. Note that any HTTP server can theoretically serve a hostlist,
5692 the build-in hostlist server makes it simply convenient to offer this
5698 * HOSTLIST - Limitations::
5702 @subsubsection Features
5706 The HOSTLIST daemon can:
5709 @item provide HELLO messages with validated addresses obtained from
5710 PEERINFO to download for other peers
5711 @item download HELLO messages and forward these message to the TRANSPORT
5712 subsystem for validation
5713 @item advertises the URL of this peer's hostlist address to other peers
5715 @item automatically learn about hostlist servers from the gossip of other
5719 @node HOSTLIST - Limitations
5720 @subsubsection HOSTLIST - Limitations
5724 The HOSTLIST daemon does not:
5727 @item verify the cryptographic information in the HELLO messages
5728 @item verify the address information in the HELLO messages
5731 @node Interacting with the HOSTLIST daemon
5732 @subsection Interacting with the HOSTLIST daemon
5736 The HOSTLIST subsystem is currently implemented as a daemon, so there is
5737 no need for the user to interact with it and therefore there is no
5738 command line tool and no API to communicate with the daemon. In the
5739 future, we can envision changing this to allow users to manually trigger
5740 the download of a hostlist.
5742 Since there is no command line interface to interact with HOSTLIST, the
5743 only way to interact with the hostlist is to use STATISTICS to obtain or
5744 modify information about the status of HOSTLIST:
5747 $ gnunet-statistics -s hostlist
5751 In particular, HOSTLIST includes a @strong{persistent} value in statistics
5752 that specifies when the hostlist server might be queried next. As this
5753 value is exponentially increasing during runtime, developers may want to
5754 reset or manually adjust it. Note that HOSTLIST (but not STATISTICS) needs
5755 to be shutdown if changes to this value are to have any effect on the
5756 daemon (as HOSTLIST does not monitor STATISTICS for changes to the
5757 download frequency).
5759 @node Hostlist security address validation
5760 @subsection Hostlist security address validation
5764 Since information obtained from other parties cannot be trusted without
5765 validation, we have to distinguish between @emph{validated} and
5766 @emph{not validated} addresses. Before using (and so trusting)
5767 information from other parties, this information has to be double-checked
5768 (validated). Address validation is not done by HOSTLIST but by the
5771 The HOSTLIST component is functionally located between the PEERINFO and
5772 the TRANSPORT subsystem. When acting as a server, the daemon obtains valid
5773 (@emph{validated}) peer information (HELLO messages) from the PEERINFO
5774 service and provides it to other peers. When acting as a client, it
5775 contacts the HOSTLIST servers specified in the configuration, downloads
5776 the (unvalidated) list of HELLO messages and forwards these information
5777 to the TRANSPORT server to validate the addresses.
5779 @cindex HOSTLIST daemon
5780 @node The HOSTLIST daemon
5781 @subsection The HOSTLIST daemon
5785 The hostlist daemon is the main component of the HOSTLIST subsystem. It is
5786 started by the ARM service and (if configured) starts the HOSTLIST client
5787 and server components.
5789 If the daemon provides a hostlist itself it can advertise it's own
5790 hostlist to other peers. To do so it sends a
5791 @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to other peers
5792 when they connect to this peer on the CORE level. This hostlist
5793 advertisement message contains the URL to access the HOSTLIST HTTP
5794 server of the sender. The daemon may also subscribe to this type of
5795 message from CORE service, and then forward these kind of message to the
5796 HOSTLIST client. The client then uses all available URLs to download peer
5797 information when necessary.
5799 When starting, the HOSTLIST daemon first connects to the CORE subsystem
5800 and if hostlist learning is enabled, registers a CORE handler to receive
5801 this kind of messages. Next it starts (if configured) the client and
5802 server. It passes pointers to CORE connect and disconnect and receive
5803 handlers where the client and server store their functions, so the daemon
5804 can notify them about CORE events.
5806 To clean up on shutdown, the daemon has a cleaning task, shutting down all
5807 subsystems and disconnecting from CORE.
5809 @cindex HOSTLIST server
5810 @node The HOSTLIST server
5811 @subsection The HOSTLIST server
5815 The server provides a way for other peers to obtain HELLOs. Basically it
5816 is a small web server other peers can connect to and download a list of
5817 HELLOs using standard HTTP; it may also advertise the URL of the hostlist
5818 to other peers connecting on CORE level.
5823 * Advertising the URL::
5826 @node The HTTP Server
5827 @subsubsection The HTTP Server
5831 During startup, the server starts a web server listening on the port
5832 specified with the HTTPPORT value (default 8080). In addition it connects
5833 to the PEERINFO service to obtain peer information. The HOSTLIST server
5834 uses the GNUNET_PEERINFO_iterate function to request HELLO information for
5835 all peers and adds their information to a new hostlist if they are
5836 suitable (expired addresses and HELLOs without addresses are both not
5837 suitable) and the maximum size for a hostlist is not exceeded
5838 (MAX_BYTES_PER_HOSTLISTS = 500000).
5839 When PEERINFO finishes (with a last NULL callback), the server destroys
5840 the previous hostlist response available for download on the web server
5841 and replaces it with the updated hostlist. The hostlist format is
5842 basically a sequence of HELLO messages (as obtained from PEERINFO) without
5843 any special tokenization. Since each HELLO message contains a size field,
5844 the response can easily be split into separate HELLO messages by the
5847 A HOSTLIST client connecting to the HOSTLIST server will receive the
5848 hostlist as a HTTP response and the the server will terminate the
5849 connection with the result code @code{HTTP 200 OK}.
5850 The connection will be closed immediately if no hostlist is available.
5852 @node Advertising the URL
5853 @subsubsection Advertising the URL
5857 The server also advertises the URL to download the hostlist to other peers
5858 if hostlist advertisement is enabled.
5859 When a new peer connects and has hostlist learning enabled, the server
5860 sends a @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT} message to this
5861 peer using the CORE service.
5863 @cindex HOSTLIST client
5864 @node The HOSTLIST client
5865 @subsection The HOSTLIST client
5869 The client provides the functionality to download the list of HELLOs from
5871 It performs a standard HTTP request to the URLs configured and learned
5872 from advertisement messages received from other peers. When a HELLO is
5873 downloaded, the HOSTLIST client forwards the HELLO to the TRANSPORT
5874 service for validation.
5876 The client supports two modes of operation:
5879 @item download of HELLOs (bootstrapping)
5880 @item learning of URLs
5889 @subsubsection Bootstrapping
5893 For bootstrapping, it schedules a task to download the hostlist from the
5895 The downloads are only performed if the number of current
5896 connections is smaller than a minimum number of connections
5898 The interval between downloads increases exponentially; however, the
5899 exponential growth is limited if it becomes longer than an hour.
5900 At that point, the frequency growth is capped at
5901 (#number of connections * 1h).
5903 Once the decision has been taken to download HELLOs, the daemon chooses a
5904 random URL from the list of known URLs. URLs can be configured in the
5905 configuration or be learned from advertisement messages.
5906 The client uses a HTTP client library (libcurl) to initiate the download
5907 using the libcurl multi interface.
5908 Libcurl passes the data to the callback_download function which
5909 stores the data in a buffer if space is available and the maximum size for
5910 a hostlist download is not exceeded (MAX_BYTES_PER_HOSTLISTS = 500000).
5911 When a full HELLO was downloaded, the HOSTLIST client offers this
5912 HELLO message to the TRANSPORT service for validation.
5913 When the download is finished or failed, statistical information about the
5914 quality of this URL is updated.
5916 @cindex HOSTLIST learning
5918 @subsubsection Learning
5922 The client also manages hostlist advertisements from other peers. The
5923 HOSTLIST daemon forwards @code{GNUNET_MESSAGE_TYPE_HOSTLIST_ADVERTISEMENT}
5924 messages to the client subsystem, which extracts the URL from the message.
5925 Next, a test of the newly obtained URL is performed by triggering a
5926 download from the new URL. If the URL works correctly, it is added to the
5927 list of working URLs.
5929 The size of the list of URLs is restricted, so if an additional server is
5930 added and the list is full, the URL with the worst quality ranking
5931 (determined through successful downloads and number of HELLOs e.g.) is
5932 discarded. During shutdown the list of URLs is saved to a file for
5933 persistance and loaded on startup. URLs from the configuration file are
5941 To start HOSTLIST by default, it has to be added to the DEFAULTSERVICES
5942 section for the ARM services. This is done in the default configuration.
5944 For more information on how to configure the HOSTLIST subsystem see the
5945 installation handbook:@
5946 Configuring the hostlist to bootstrap@
5947 Configuring your peer to provide a hostlist
5949 @cindex IDENTITY Subsystem
5950 @node IDENTITY Subsystem
5951 @section IDENTITY Subsystem
5955 Identities of "users" in GNUnet are called egos.
5956 Egos can be used as pseudonyms ("fake names") or be tied to an
5957 organization (for example, "GNU") or even the actual identity of a human.
5958 GNUnet users are expected to have many egos. They might have one tied to
5959 their real identity, some for organizations they manage, and more for
5960 different domains where they want to operate under a pseudonym.
5962 The IDENTITY service allows users to manage their egos. The identity
5963 service manages the private keys egos of the local user; it does not
5964 manage identities of other users (public keys). Public keys for other
5965 users need names to become manageable. GNUnet uses the
5966 @dfn{GNU Name System} (GNS) to give names to other users and manage their
5967 public keys securely. This chapter is about the IDENTITY service,
5968 which is about the management of private keys.
5970 On the network, an ego corresponds to an ECDSA key (over Curve25519,
5971 using RFC 6979, as required by GNS). Thus, users can perform actions
5972 under a particular ego by using (signing with) a particular private key.
5973 Other users can then confirm that the action was really performed by that
5974 ego by checking the signature against the respective public key.
5976 The IDENTITY service allows users to associate a human-readable name with
5977 each ego. This way, users can use names that will remind them of the
5978 purpose of a particular ego.
5979 The IDENTITY service will store the respective private keys and
5980 allows applications to access key information by name.
5981 Users can change the name that is locally (!) associated with an ego.
5982 Egos can also be deleted, which means that the private key will be removed
5983 and it thus will not be possible to perform actions with that ego in the
5986 Additionally, the IDENTITY subsystem can associate service functions with
5988 For example, GNS requires the ego that should be used for the shorten
5989 zone. GNS will ask IDENTITY for an ego for the "gns-short" service.
5990 The IDENTITY service has a mapping of such service strings to the name of
5991 the ego that the user wants to use for this service, for example
5992 "my-short-zone-ego".
5994 Finally, the IDENTITY API provides access to a special ego, the
5995 anonymous ego. The anonymous ego is special in that its private key is not
5996 really private, but fixed and known to everyone.
5997 Thus, anyone can perform actions as anonymous. This can be useful as with
5998 this trick, code does not have to contain a special case to distinguish
5999 between anonymous and pseudonymous egos.
6002 * libgnunetidentity::
6003 * The IDENTITY Client-Service Protocol::
6006 @cindex libgnunetidentity
6007 @node libgnunetidentity
6008 @subsection libgnunetidentity
6013 * Connecting to the service::
6014 * Operations on Egos::
6015 * The anonymous Ego::
6016 * Convenience API to lookup a single ego::
6017 * Associating egos with service functions::
6020 @node Connecting to the service
6021 @subsubsection Connecting to the service
6025 First, typical clients connect to the identity service using
6026 @code{GNUNET_IDENTITY_connect}. This function takes a callback as a
6028 If the given callback parameter is non-null, it will be invoked to notify
6029 the application about the current state of the identities in the system.
6032 @item First, it will be invoked on all known egos at the time of the
6033 connection. For each ego, a handle to the ego and the user's name for the
6034 ego will be passed to the callback. Furthermore, a @code{void **} context
6035 argument will be provided which gives the client the opportunity to
6036 associate some state with the ego.
6037 @item Second, the callback will be invoked with NULL for the ego, the name
6038 and the context. This signals that the (initial) iteration over all egos
6040 @item Then, the callback will be invoked whenever something changes about
6042 If an ego is renamed, the callback is invoked with the ego handle of the
6043 ego that was renamed, and the new name. If an ego is deleted, the callback
6044 is invoked with the ego handle and a name of NULL. In the deletion case,
6045 the application should also release resources stored in the context.
6046 @item When the application destroys the connection to the identity service
6047 using @code{GNUNET_IDENTITY_disconnect}, the callback is again invoked
6048 with the ego and a name of NULL (equivalent to deletion of the egos).
6049 This should again be used to clean up the per-ego context.
6052 The ego handle passed to the callback remains valid until the callback is
6053 invoked with a name of NULL, so it is safe to store a reference to the
6056 @node Operations on Egos
6057 @subsubsection Operations on Egos
6061 Given an ego handle, the main operations are to get its associated private
6062 key using @code{GNUNET_IDENTITY_ego_get_private_key} or its associated
6063 public key using @code{GNUNET_IDENTITY_ego_get_public_key}.
6065 The other operations on egos are pretty straightforward.
6066 Using @code{GNUNET_IDENTITY_create}, an application can request the
6067 creation of an ego by specifying the desired name.
6068 The operation will fail if that name is
6069 already in use. Using @code{GNUNET_IDENTITY_rename} the name of an
6070 existing ego can be changed. Finally, egos can be deleted using
6071 @code{GNUNET_IDENTITY_delete}. All of these operations will trigger
6072 updates to the callback given to the @code{GNUNET_IDENTITY_connect}
6073 function of all applications that are connected with the identity service
6074 at the time. @code{GNUNET_IDENTITY_cancel} can be used to cancel the
6075 operations before the respective continuations would be called.
6076 It is not guaranteed that the operation will not be completed anyway,
6077 only the continuation will no longer be called.
6079 @node The anonymous Ego
6080 @subsubsection The anonymous Ego
6084 A special way to obtain an ego handle is to call
6085 @code{GNUNET_IDENTITY_ego_get_anonymous}, which returns an ego for the
6086 "anonymous" user --- anyone knows and can get the private key for this
6087 user, so it is suitable for operations that are supposed to be anonymous
6088 but require signatures (for example, to avoid a special path in the code).
6089 The anonymous ego is always valid and accessing it does not require a
6090 connection to the identity service.
6092 @node Convenience API to lookup a single ego
6093 @subsubsection Convenience API to lookup a single ego
6096 As applications commonly simply have to lookup a single ego, there is a
6097 convenience API to do just that. Use @code{GNUNET_IDENTITY_ego_lookup} to
6098 lookup a single ego by name. Note that this is the user's name for the
6099 ego, not the service function. The resulting ego will be returned via a
6100 callback and will only be valid during that callback. The operation can
6101 be canceled via @code{GNUNET_IDENTITY_ego_lookup_cancel}
6102 (cancellation is only legal before the callback is invoked).
6104 @node Associating egos with service functions
6105 @subsubsection Associating egos with service functions
6108 The @code{GNUNET_IDENTITY_set} function is used to associate a particular
6109 ego with a service function. The name used by the service and the ego are
6111 Afterwards, the service can use its name to lookup the associated ego
6112 using @code{GNUNET_IDENTITY_get}.
6114 @node The IDENTITY Client-Service Protocol
6115 @subsection The IDENTITY Client-Service Protocol
6119 A client connecting to the identity service first sends a message with
6121 @code{GNUNET_MESSAGE_TYPE_IDENTITY_START} to the service. After that, the
6122 client will receive information about changes to the egos by receiving
6123 messages of type @code{GNUNET_MESSAGE_TYPE_IDENTITY_UPDATE}.
6124 Those messages contain the private key of the ego and the user's name of
6125 the ego (or zero bytes for the name to indicate that the ego was deleted).
6126 A special bit @code{end_of_list} is used to indicate the end of the
6127 initial iteration over the identity service's egos.
6129 The client can trigger changes to the egos by sending @code{CREATE},
6130 @code{RENAME} or @code{DELETE} messages.
6131 The CREATE message contains the private key and the desired name.@
6132 The RENAME message contains the old name and the new name.@
6133 The DELETE message only needs to include the name of the ego to delete.@
6134 The service responds to each of these messages with a @code{RESULT_CODE}
6135 message which indicates success or error of the operation, and possibly
6136 a human-readable error message.
6138 Finally, the client can bind the name of a service function to an ego by
6139 sending a @code{SET_DEFAULT} message with the name of the service function
6140 and the private key of the ego.
6141 Such bindings can then be resolved using a @code{GET_DEFAULT} message,
6142 which includes the name of the service function. The identity service
6143 will respond to a GET_DEFAULT request with a SET_DEFAULT message
6144 containing the respective information, or with a RESULT_CODE to
6147 @cindex NAMESTORE Subsystem
6148 @node NAMESTORE Subsystem
6149 @section NAMESTORE Subsystem
6151 The NAMESTORE subsystem provides persistent storage for local GNS zone
6152 information. All local GNS zone information are managed by NAMESTORE. It
6153 provides both the functionality to administer local GNS information (e.g.
6154 delete and add records) as well as to retrieve GNS information (e.g to
6155 list name information in a client).
6156 NAMESTORE does only manage the persistent storage of zone information
6157 belonging to the user running the service: GNS information from other
6158 users obtained from the DHT are stored by the NAMECACHE subsystem.
6160 NAMESTORE uses a plugin-based database backend to store GNS information
6161 with good performance. Here sqlite, MySQL and PostgreSQL are supported
6163 NAMESTORE clients interact with the IDENTITY subsystem to obtain
6164 cryptographic information about zones based on egos as described with the
6165 IDENTITY subsystem, but internally NAMESTORE refers to zones using the
6167 In addition, it collaborates with the NAMECACHE subsystem and
6168 stores zone information when local information are modified in the
6169 GNS cache to increase look-up performance for local information.
6171 NAMESTORE provides functionality to look-up and store records, to iterate
6172 over a specific or all zones and to monitor zones for changes. NAMESTORE
6173 functionality can be accessed using the NAMESTORE api or the NAMESTORE
6177 * libgnunetnamestore::
6180 @cindex libgnunetnamestore
6181 @node libgnunetnamestore
6182 @subsection libgnunetnamestore
6184 To interact with NAMESTORE clients first connect to the NAMESTORE service
6185 using the @code{GNUNET_NAMESTORE_connect} passing a configuration handle.
6186 As a result they obtain a NAMESTORE handle, they can use for operations,
6187 or NULL is returned if the connection failed.
6189 To disconnect from NAMESTORE, clients use
6190 @code{GNUNET_NAMESTORE_disconnect} and specify the handle to disconnect.
6192 NAMESTORE internally uses the ECDSA private key to refer to zones. These
6193 private keys can be obtained from the IDENTITY subsytem.
6194 Here @emph{egos} @emph{can be used to refer to zones or the default ego
6195 assigned to the GNS subsystem can be used to obtained the master zone's
6200 * Editing Zone Information::
6201 * Iterating Zone Information::
6202 * Monitoring Zone Information::
6205 @node Editing Zone Information
6206 @subsubsection Editing Zone Information
6210 NAMESTORE provides functions to lookup records stored under a label in a
6211 zone and to store records under a label in a zone.
6213 To store (and delete) records, the client uses the
6214 @code{GNUNET_NAMESTORE_records_store} function and has to provide
6215 namestore handle to use, the private key of the zone, the label to store
6216 the records under, the records and number of records plus an callback
6218 After the operation is performed NAMESTORE will call the provided
6219 callback function with the result GNUNET_SYSERR on failure
6220 (including timeout/queue drop/failure to validate), GNUNET_NO if content
6221 was already there or not found GNUNET_YES (or other positive value) on
6222 success plus an additional error message.
6224 Records are deleted by using the store command with 0 records to store.
6225 It is important to note, that records are not merged when records exist
6227 So a client has first to retrieve records, merge with existing records
6228 and then store the result.
6230 To perform a lookup operation, the client uses the
6231 @code{GNUNET_NAMESTORE_records_store} function. Here it has to pass the
6232 namestore handle, the private key of the zone and the label. It also has
6233 to provide a callback function which will be called with the result of
6234 the lookup operation:
6235 the zone for the records, the label, and the records including the
6236 number of records included.
6238 A special operation is used to set the preferred nickname for a zone.
6239 This nickname is stored with the zone and is automatically merged with
6240 all labels and records stored in a zone. Here the client uses the
6241 @code{GNUNET_NAMESTORE_set_nick} function and passes the private key of
6242 the zone, the nickname as string plus a the callback with the result of
6245 @node Iterating Zone Information
6246 @subsubsection Iterating Zone Information
6250 A client can iterate over all information in a zone or all zones managed
6252 Here a client uses the @code{GNUNET_NAMESTORE_zone_iteration_start}
6253 function and passes the namestore handle, the zone to iterate over and a
6254 callback function to call with the result.
6255 If the client wants to iterate over all the WHAT!? FIXME, it passes NULL for the zone.
6256 A @code{GNUNET_NAMESTORE_ZoneIterator} handle is returned to be used to
6259 NAMESTORE calls the callback for every result and expects the client to
6260 call @code{GNUNET_NAMESTORE_zone_iterator_next} to continue to iterate or
6261 @code{GNUNET_NAMESTORE_zone_iterator_stop} to interrupt the iteration.
6262 When NAMESTORE reached the last item it will call the callback with a
6263 NULL value to indicate.
6265 @node Monitoring Zone Information
6266 @subsubsection Monitoring Zone Information
6270 Clients can also monitor zones to be notified about changes. Here the
6271 clients uses the @code{GNUNET_NAMESTORE_zone_monitor_start} function and
6272 passes the private key of the zone and and a callback function to call
6273 with updates for a zone.
6274 The client can specify to obtain zone information first by iterating over
6275 the zone and specify a synchronization callback to be called when the
6276 client and the namestore are synced.
6278 On an update, NAMESTORE will call the callback with the private key of the
6279 zone, the label and the records and their number.
6281 To stop monitoring, the client calls
6282 @code{GNUNET_NAMESTORE_zone_monitor_stop} and passes the handle obtained
6283 from the function to start the monitoring.
6285 @cindex PEERINFO Subsystem
6286 @node PEERINFO Subsystem
6287 @section PEERINFO Subsystem
6291 The PEERINFO subsystem is used to store verified (validated) information
6292 about known peers in a persistent way. It obtains these addresses for
6293 example from TRANSPORT service which is in charge of address validation.
6294 Validation means that the information in the HELLO message are checked by
6295 connecting to the addresses and performing a cryptographic handshake to
6296 authenticate the peer instance stating to be reachable with these
6298 Peerinfo does not validate the HELLO messages itself but only stores them
6299 and gives them to interested clients.
6301 As future work, we think about moving from storing just HELLO messages to
6302 providing a generic persistent per-peer information store.
6303 More and more subsystems tend to need to store per-peer information in
6305 To not duplicate this functionality we plan to provide a PEERSTORE
6306 service providing this functionality.
6309 * PEERINFO - Features::
6310 * PEERINFO - Limitations::
6311 * DeveloperPeer Information::
6313 * Managing Information::
6314 * Obtaining Information::
6315 * The PEERINFO Client-Service Protocol::
6316 * libgnunetpeerinfo::
6319 @node PEERINFO - Features
6320 @subsection PEERINFO - Features
6325 @item Persistent storage
6326 @item Client notification mechanism on update
6327 @item Periodic clean up for expired information
6328 @item Differentiation between public and friend-only HELLO
6331 @node PEERINFO - Limitations
6332 @subsection PEERINFO - Limitations
6336 @item Does not perform HELLO validation
6339 @node DeveloperPeer Information
6340 @subsection DeveloperPeer Information
6344 The PEERINFO subsystem stores these information in the form of HELLO
6345 messages you can think of as business cards.
6346 These HELLO messages contain the public key of a peer and the addresses
6347 a peer can be reached under.
6348 The addresses include an expiration date describing how long they are
6349 valid. This information is updated regularly by the TRANSPORT service by
6350 revalidating the address.
6351 If an address is expired and not renewed, it can be removed from the
6354 Some peer do not want to have their HELLO messages distributed to other
6355 peers, especially when GNUnet's friend-to-friend modus is enabled.
6356 To prevent this undesired distribution. PEERINFO distinguishes between
6357 @emph{public} and @emph{friend-only} HELLO messages.
6358 Public HELLO messages can be freely distributed to other (possibly
6359 unknown) peers (for example using the hostlist, gossiping, broadcasting),
6360 whereas friend-only HELLO messages may not be distributed to other peers.
6361 Friend-only HELLO messages have an additional flag @code{friend_only} set
6362 internally. For public HELLO message this flag is not set.
6363 PEERINFO does and cannot not check if a client is allowed to obtain a
6364 specific HELLO type.
6366 The HELLO messages can be managed using the GNUnet HELLO library.
6367 Other GNUnet systems can obtain these information from PEERINFO and use
6368 it for their purposes.
6369 Clients are for example the HOSTLIST component providing these
6370 information to other peers in form of a hostlist or the TRANSPORT
6371 subsystem using these information to maintain connections to other peers.
6378 During startup the PEERINFO services loads persistent HELLOs from disk.
6379 First PEERINFO parses the directory configured in the HOSTS value of the
6380 @code{PEERINFO} configuration section to store PEERINFO information.
6381 For all files found in this directory valid HELLO messages are extracted.
6382 In addition it loads HELLO messages shipped with the GNUnet distribution.
6383 These HELLOs are used to simplify network bootstrapping by providing
6384 valid peer information with the distribution.
6385 The use of these HELLOs can be prevented by setting the
6386 @code{USE_INCLUDED_HELLOS} in the @code{PEERINFO} configuration section to
6387 @code{NO}. Files containing invalid information are removed.
6389 @node Managing Information
6390 @subsection Managing Information
6394 The PEERINFO services stores information about known PEERS and a single
6395 HELLO message for every peer.
6396 A peer does not need to have a HELLO if no information are available.
6397 HELLO information from different sources, for example a HELLO obtained
6398 from a remote HOSTLIST and a second HELLO stored on disk, are combined
6399 and merged into one single HELLO message per peer which will be given to
6400 clients. During this merge process the HELLO is immediately written to
6401 disk to ensure persistence.
6403 PEERINFO in addition periodically scans the directory where information
6404 are stored for empty HELLO messages with expired TRANSPORT addresses.
6405 This periodic task scans all files in the directory and recreates the
6406 HELLO messages it finds.
6407 Expired TRANSPORT addresses are removed from the HELLO and if the
6408 HELLO does not contain any valid addresses, it is discarded and removed
6411 @node Obtaining Information
6412 @subsection Obtaining Information
6416 When a client requests information from PEERINFO, PEERINFO performs a
6417 lookup for the respective peer or all peers if desired and transmits this
6418 information to the client.
6419 The client can specify if friend-only HELLOs have to be included or not
6420 and PEERINFO filters the respective HELLO messages before transmitting
6423 To notify clients about changes to PEERINFO information, PEERINFO
6424 maintains a list of clients interested in this notifications.
6425 Such a notification occurs if a HELLO for a peer was updated (due to a
6426 merge for example) or a new peer was added.
6428 @node The PEERINFO Client-Service Protocol
6429 @subsection The PEERINFO Client-Service Protocol
6433 To connect and disconnect to and from the PEERINFO Service PEERINFO
6434 utilizes the util client/server infrastructure, so no special messages
6435 types are used here.
6437 To add information for a peer, the plain HELLO message is transmitted to
6438 the service without any wrapping. All pieces of information required are
6439 stored within the HELLO message.
6440 The PEERINFO service provides a message handler accepting and processing
6441 these HELLO messages.
6443 When obtaining PEERINFO information using the iterate functionality
6444 specific messages are used. To obtain information for all peers, a
6445 @code{struct ListAllPeersMessage} with message type
6446 @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET_ALL} and a flag
6447 include_friend_only to indicate if friend-only HELLO messages should be
6448 included are transmitted. If information for a specific peer is required
6449 a @code{struct ListAllPeersMessage} with
6450 @code{GNUNET_MESSAGE_TYPE_PEERINFO_GET} containing the peer identity is
6453 For both variants the PEERINFO service replies for each HELLO message it
6454 wants to transmit with a @code{struct ListAllPeersMessage} with type
6455 @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO} containing the plain HELLO.
6456 The final message is @code{struct GNUNET_MessageHeader} with type
6457 @code{GNUNET_MESSAGE_TYPE_PEERINFO_INFO}. If the client receives this
6458 message, it can proceed with the next request if any is pending.
6460 @node libgnunetpeerinfo
6461 @subsection libgnunetpeerinfo
6465 The PEERINFO API consists mainly of three different functionalities:
6468 @item maintaining a connection to the service
6469 @item adding new information to the PEERINFO service
6470 @item retrieving information from the PEERINFO service
6474 * Connecting to the PEERINFO Service::
6475 * Adding Information to the PEERINFO Service::
6476 * Obtaining Information from the PEERINFO Service::
6479 @node Connecting to the PEERINFO Service
6480 @subsubsection Connecting to the PEERINFO Service
6484 To connect to the PEERINFO service the function
6485 @code{GNUNET_PEERINFO_connect} is used, taking a configuration handle as
6486 an argument, and to disconnect from PEERINFO the function
6487 @code{GNUNET_PEERINFO_disconnect}, taking the PEERINFO
6488 handle returned from the connect function has to be called.
6490 @node Adding Information to the PEERINFO Service
6491 @subsubsection Adding Information to the PEERINFO Service
6495 @code{GNUNET_PEERINFO_add_peer} adds a new peer to the PEERINFO subsystem
6496 storage. This function takes the PEERINFO handle as an argument, the HELLO
6497 message to store and a continuation with a closure to be called with the
6498 result of the operation.
6499 The @code{GNUNET_PEERINFO_add_peer} returns a handle to this operation
6500 allowing to cancel the operation with the respective cancel function
6501 @code{GNUNET_PEERINFO_add_peer_cancel}. To retrieve information from
6502 PEERINFO you can iterate over all information stored with PEERINFO or you
6503 can tell PEERINFO to notify if new peer information are available.
6505 @node Obtaining Information from the PEERINFO Service
6506 @subsubsection Obtaining Information from the PEERINFO Service
6510 To iterate over information in PEERINFO you use
6511 @code{GNUNET_PEERINFO_iterate}.
6512 This function expects the PEERINFO handle, a flag if HELLO messages
6513 intended for friend only mode should be included, a timeout how long the
6514 operation should take and a callback with a callback closure to be called
6516 If you want to obtain information for a specific peer, you can specify
6517 the peer identity, if this identity is NULL, information for all peers are
6518 returned. The function returns a handle to allow to cancel the operation
6519 using @code{GNUNET_PEERINFO_iterate_cancel}.
6521 To get notified when peer information changes, you can use
6522 @code{GNUNET_PEERINFO_notify}.
6523 This function expects a configuration handle and a flag if friend-only
6524 HELLO messages should be included. The PEERINFO service will notify you
6525 about every change and the callback function will be called to notify you
6526 about changes. The function returns a handle to cancel notifications
6527 with @code{GNUNET_PEERINFO_notify_cancel}.
6529 @cindex PEERSTORE Subsystem
6530 @node PEERSTORE Subsystem
6531 @section PEERSTORE Subsystem
6535 GNUnet's PEERSTORE subsystem offers persistent per-peer storage for other
6536 GNUnet subsystems. GNUnet subsystems can use PEERSTORE to persistently
6537 store and retrieve arbitrary data.
6538 Each data record stored with PEERSTORE contains the following fields:
6541 @item subsystem: Name of the subsystem responsible for the record.
6542 @item peerid: Identity of the peer this record is related to.
6543 @item key: a key string identifying the record.
6544 @item value: binary record value.
6545 @item expiry: record expiry date.
6551 * libgnunetpeerstore::
6555 @subsection Functionality
6559 Subsystems can store any type of value under a (subsystem, peerid, key)
6560 combination. A "replace" flag set during store operations forces the
6561 PEERSTORE to replace any old values stored under the same
6562 (subsystem, peerid, key) combination with the new value.
6563 Additionally, an expiry date is set after which the record is *possibly*
6564 deleted by PEERSTORE.
6566 Subsystems can iterate over all values stored under any of the following
6567 combination of fields:
6571 @item (subsystem, peerid)
6572 @item (subsystem, key)
6573 @item (subsystem, peerid, key)
6576 Subsystems can also request to be notified about any new values stored
6577 under a (subsystem, peerid, key) combination by sending a "watch"
6578 request to PEERSTORE.
6581 @subsection Architecture
6585 PEERSTORE implements the following components:
6588 @item PEERSTORE service: Handles store, iterate and watch operations.
6589 @item PEERSTORE API: API to be used by other subsystems to communicate and
6590 issue commands to the PEERSTORE service.
6591 @item PEERSTORE plugins: Handles the persistent storage. At the moment,
6592 only an "sqlite" plugin is implemented.
6595 @cindex libgnunetpeerstore
6596 @node libgnunetpeerstore
6597 @subsection libgnunetpeerstore
6601 libgnunetpeerstore is the library containing the PEERSTORE API. Subsystems
6602 wishing to communicate with the PEERSTORE service use this API to open a
6603 connection to PEERSTORE. This is done by calling
6604 @code{GNUNET_PEERSTORE_connect} which returns a handle to the newly
6606 This handle has to be used with any further calls to the API.
6608 To store a new record, the function @code{GNUNET_PEERSTORE_store} is to
6609 be used which requires the record fields and a continuation function that
6610 will be called by the API after the STORE request is sent to the
6612 Note that calling the continuation function does not mean that the record
6613 is successfully stored, only that the STORE request has been successfully
6614 sent to the PEERSTORE service.
6615 @code{GNUNET_PEERSTORE_store_cancel} can be called to cancel the STORE
6616 request only before the continuation function has been called.
6618 To iterate over stored records, the function
6619 @code{GNUNET_PEERSTORE_iterate} is
6620 to be used. @emph{peerid} and @emph{key} can be set to NULL. An iterator
6621 callback function will be called with each matching record found and a
6622 NULL record at the end to signal the end of result set.
6623 @code{GNUNET_PEERSTORE_iterate_cancel} can be used to cancel the ITERATE
6624 request before the iterator callback is called with a NULL record.
6626 To be notified with new values stored under a (subsystem, peerid, key)
6627 combination, the function @code{GNUNET_PEERSTORE_watch} is to be used.
6628 This will register the watcher with the PEERSTORE service, any new
6629 records matching the given combination will trigger the callback
6630 function passed to @code{GNUNET_PEERSTORE_watch}. This continues until
6631 @code{GNUNET_PEERSTORE_watch_cancel} is called or the connection to the
6632 service is destroyed.
6634 After the connection is no longer needed, the function
6635 @code{GNUNET_PEERSTORE_disconnect} can be called to disconnect from the
6637 Any pending ITERATE or WATCH requests will be destroyed.
6638 If the @code{sync_first} flag is set to @code{GNUNET_YES}, the API will
6639 delay the disconnection until all pending STORE requests are sent to
6640 the PEERSTORE service, otherwise, the pending STORE requests will be
6643 @cindex SET Subsystem
6645 @section SET Subsystem
6649 The SET service implements efficient set operations between two peers
6651 Currently, set union and set intersection are the only supported
6652 operations. Elements of a set consist of an @emph{element type} and
6653 arbitrary binary @emph{data}.
6654 The size of an element's data is limited to around 62 KB.
6658 * Set Modifications::
6662 * The SET Client-Service Protocol::
6663 * The SET Intersection Peer-to-Peer Protocol::
6664 * The SET Union Peer-to-Peer Protocol::
6668 @subsection Local Sets
6672 Sets created by a local client can be modified and reused for multiple
6673 operations. As each set operation requires potentially expensive special
6674 auxiliary data to be computed for each element of a set, a set can only
6675 participate in one type of set operation (i.e. union or intersection).
6676 The type of a set is determined upon its creation.
6677 If a the elements of a set are needed for an operation of a different
6678 type, all of the set's element must be copied to a new set of appropriate
6681 @node Set Modifications
6682 @subsection Set Modifications
6686 Even when set operations are active, one can add to and remove elements
6688 However, these changes will only be visible to operations that have been
6689 created after the changes have taken place. That is, every set operation
6690 only sees a snapshot of the set from the time the operation was started.
6691 This mechanism is @emph{not} implemented by copying the whole set, but by
6692 attaching @emph{generation information} to each element and operation.
6694 @node Set Operations
6695 @subsection Set Operations
6699 Set operations can be started in two ways: Either by accepting an
6700 operation request from a remote peer, or by requesting a set operation
6702 Set operations are uniquely identified by the involved @emph{peers}, an
6703 @emph{application id} and the @emph{operation type}.
6705 The client is notified of incoming set operations by @emph{set listeners}.
6706 A set listener listens for incoming operations of a specific operation
6707 type and application id.
6708 Once notified of an incoming set request, the client can accept the set
6709 request (providing a local set for the operation) or reject it.
6711 @node Result Elements
6712 @subsection Result Elements
6716 The SET service has three @emph{result modes} that determine how an
6717 operation's result set is delivered to the client:
6720 @item @strong{Full Result Set.} All elements of set resulting from the set
6721 operation are returned to the client.
6722 @item @strong{Added Elements.} Only elements that result from the
6723 operation and are not already in the local peer's set are returned.
6724 Note that for some operations (like set intersection) this result mode
6725 will never return any elements.
6726 This can be useful if only the remove peer is actually interested in
6727 the result of the set operation.
6728 @item @strong{Removed Elements.} Only elements that are in the local
6729 peer's initial set but not in the operation's result set are returned.
6730 Note that for some operations (like set union) this result mode will
6731 never return any elements. This can be useful if only the remove peer is
6732 actually interested in the result of the set operation.
6735 @cindex libgnunetset
6737 @subsection libgnunetset
6746 * The Result Callback::
6754 New sets are created with @code{GNUNET_SET_create}. Both the local peer's
6755 configuration (as each set has its own client connection) and the
6756 operation type must be specified.
6757 The set exists until either the client calls @code{GNUNET_SET_destroy} or
6758 the client's connection to the service is disrupted.
6759 In the latter case, the client is notified by the return value of
6760 functions dealing with sets. This return value must always be checked.
6762 Elements are added and removed with @code{GNUNET_SET_add_element} and
6763 @code{GNUNET_SET_remove_element}.
6766 @subsubsection Listeners
6770 Listeners are created with @code{GNUNET_SET_listen}. Each time time a
6771 remote peer suggests a set operation with an application id and operation
6772 type matching a listener, the listener's callback is invoked.
6773 The client then must synchronously call either @code{GNUNET_SET_accept}
6774 or @code{GNUNET_SET_reject}. Note that the operation will not be started
6775 until the client calls @code{GNUNET_SET_commit}
6776 (see Section "Supplying a Set").
6779 @subsubsection Operations
6783 Operations to be initiated by the local peer are created with
6784 @code{GNUNET_SET_prepare}. Note that the operation will not be started
6785 until the client calls @code{GNUNET_SET_commit}
6786 (see Section "Supplying a Set").
6788 @node Supplying a Set
6789 @subsubsection Supplying a Set
6793 To create symmetry between the two ways of starting a set operation
6794 (accepting and initiating it), the operation handles returned by
6795 @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare} do not yet have a
6796 set to operate on, thus they can not do any work yet.
6798 The client must call @code{GNUNET_SET_commit} to specify a set to use for
6799 an operation. @code{GNUNET_SET_commit} may only be called once per set
6802 @node The Result Callback
6803 @subsubsection The Result Callback
6807 Clients must specify both a result mode and a result callback with
6808 @code{GNUNET_SET_accept} and @code{GNUNET_SET_prepare}. The result
6809 callback with a status indicating either that an element was received, or
6810 the operation failed or succeeded.
6811 The interpretation of the received element depends on the result mode.
6812 The callback needs to know which result mode it is used in, as the
6813 arguments do not indicate if an element is part of the full result set,
6814 or if it is in the difference between the original set and the final set.
6816 @node The SET Client-Service Protocol
6817 @subsection The SET Client-Service Protocol
6824 * Initiating Operations::
6826 * Results and Operation Status::
6831 @subsubsection Creating Sets
6835 For each set of a client, there exists a client connection to the service.
6836 Sets are created by sending the @code{GNUNET_SERVICE_SET_CREATE} message
6837 over a new client connection. Multiple operations for one set are
6838 multiplexed over one client connection, using a request id supplied by
6842 @subsubsection Listeners2
6846 Each listener also requires a seperate client connection. By sending the
6847 @code{GNUNET_SERVICE_SET_LISTEN} message, the client notifies the service
6848 of the application id and operation type it is interested in. A client
6849 rejects an incoming request by sending @code{GNUNET_SERVICE_SET_REJECT}
6850 on the listener's client connection.
6851 In contrast, when accepting an incoming request, a
6852 @code{GNUNET_SERVICE_SET_ACCEPT} message must be sent over the@ set that
6853 is supplied for the set operation.
6855 @node Initiating Operations
6856 @subsubsection Initiating Operations
6860 Operations with remote peers are initiated by sending a
6861 @code{GNUNET_SERVICE_SET_EVALUATE} message to the service. The@ client
6862 connection that this message is sent by determines the set to use.
6864 @node Modifying Sets
6865 @subsubsection Modifying Sets
6869 Sets are modified with the @code{GNUNET_SERVICE_SET_ADD} and
6870 @code{GNUNET_SERVICE_SET_REMOVE} messages.
6874 @c %* Results and Operation Status::
6875 @c %* Iterating Sets::
6878 @node Results and Operation Status
6879 @subsubsection Results and Operation Status
6882 The service notifies the client of result elements and success/failure of
6883 a set operation with the @code{GNUNET_SERVICE_SET_RESULT} message.
6885 @node Iterating Sets
6886 @subsubsection Iterating Sets
6890 All elements of a set can be requested by sending
6891 @code{GNUNET_SERVICE_SET_ITER_REQUEST}. The server responds with
6892 @code{GNUNET_SERVICE_SET_ITER_ELEMENT} and eventually terminates the
6893 iteration with @code{GNUNET_SERVICE_SET_ITER_DONE}.
6894 After each received element, the client
6895 must send @code{GNUNET_SERVICE_SET_ITER_ACK}. Note that only one set
6896 iteration may be active for a set at any given time.
6898 @node The SET Intersection Peer-to-Peer Protocol
6899 @subsection The SET Intersection Peer-to-Peer Protocol
6903 The intersection protocol operates over CADET and starts with a
6904 GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer
6905 initiating the operation to the peer listening for inbound requests.
6906 It includes the number of elements of the initiating peer, which is used
6907 to decide which side will send a Bloom filter first.
6909 The listening peer checks if the operation type and application
6910 identifier are acceptable for its current state.
6911 If not, it responds with a GNUNET_MESSAGE_TYPE_SET_RESULT and a status of
6912 GNUNET_SET_STATUS_FAILURE (and terminates the CADET channel).
6914 If the application accepts the request, the listener sends back a
6915 @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} if it has
6916 more elements in the set than the client.
6917 Otherwise, it immediately starts with the Bloom filter exchange.
6918 If the initiator receives a
6919 @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_ELEMENT_INFO} response,
6920 it beings the Bloom filter exchange, unless the set size is indicated to
6921 be zero, in which case the intersection is considered finished after
6922 just the initial handshake.
6926 * The Bloom filter exchange::
6930 @node The Bloom filter exchange
6931 @subsubsection The Bloom filter exchange
6935 In this phase, each peer transmits a Bloom filter over the remaining
6936 keys of the local set to the other peer using a
6937 @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_BF} message. This
6938 message additionally includes the number of elements left in the sender's
6939 set, as well as the XOR over all of the keys in that set.
6941 The number of bits 'k' set per element in the Bloom filter is calculated
6942 based on the relative size of the two sets.
6943 Furthermore, the size of the Bloom filter is calculated based on 'k' and
6944 the number of elements in the set to maximize the amount of data filtered
6945 per byte transmitted on the wire (while avoiding an excessively high
6946 number of iterations).
6948 The receiver of the message removes all elements from its local set that
6949 do not pass the Bloom filter test.
6950 It then checks if the set size of the sender and the XOR over the keys
6951 match what is left of its own set. If they do, it sends a
6952 @code{GNUNET_MESSAGE_TYPE_SET_INTERSECTION_P2P_DONE} back to indicate
6953 that the latest set is the final result.
6954 Otherwise, the receiver starts another Bloom filter exchange, except
6955 this time as the sender.
6962 Bloomfilter operations are probabilistic: With some non-zero probability
6963 the test may incorrectly say an element is in the set, even though it is
6966 To mitigate this problem, the intersection protocol iterates exchanging
6967 Bloom filters using a different random 32-bit salt in each iteration (the
6968 salt is also included in the message).
6969 With different salts, set operations may fail for different elements.
6970 Merging the results from the executions, the probability of failure drops
6973 The iterations terminate once both peers have established that they have
6974 sets of the same size, and where the XOR over all keys computes the same
6975 512-bit value (leaving a failure probability of 2-511).
6977 @node The SET Union Peer-to-Peer Protocol
6978 @subsection The SET Union Peer-to-Peer Protocol
6982 The SET union protocol is based on Eppstein's efficient set reconciliation
6983 without prior context. You should read this paper first if you want to
6984 understand the protocol.
6986 The union protocol operates over CADET and starts with a
6987 GNUNET_MESSAGE_TYPE_SET_P2P_OPERATION_REQUEST being sent by the peer
6988 initiating the operation to the peer listening for inbound requests.
6989 It includes the number of elements of the initiating peer, which is
6992 The listening peer checks if the operation type and application
6993 identifier are acceptable for its current state. If not, it responds with
6994 a @code{GNUNET_MESSAGE_TYPE_SET_RESULT} and a status of
6995 @code{GNUNET_SET_STATUS_FAILURE} (and terminates the CADET channel).
6997 If the application accepts the request, it sends back a strata estimator
6998 using a message of type GNUNET_MESSAGE_TYPE_SET_UNION_P2P_SE. The
6999 initiator evaluates the strata estimator and initiates the exchange of
7000 invertible Bloom filters, sending a GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF.
7002 During the IBF exchange, if the receiver cannot invert the Bloom filter or
7003 detects a cycle, it sends a larger IBF in response (up to a defined
7004 maximum limit; if that limit is reached, the operation fails).
7005 Elements decoded while processing the IBF are transmitted to the other
7006 peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS, or requested from the
7007 other peer using GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS messages,
7008 depending on the sign observed during decoding of the IBF.
7009 Peers respond to a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENT_REQUESTS message
7010 with the respective element in a GNUNET_MESSAGE_TYPE_SET_P2P_ELEMENTS
7011 message. If the IBF fully decodes, the peer responds with a
7012 GNUNET_MESSAGE_TYPE_SET_UNION_P2P_DONE message instead of another
7013 GNUNET_MESSAGE_TYPE_SET_UNION_P2P_IBF.
7015 All Bloom filter operations use a salt to mingle keys before hashing them
7016 into buckets, such that future iterations have a fresh chance of
7017 succeeding if they failed due to collisions before.
7019 @cindex STATISTICS Subsystem
7020 @node STATISTICS Subsystem
7021 @section STATISTICS Subsystem
7025 In GNUnet, the STATISTICS subsystem offers a central place for all
7026 subsystems to publish unsigned 64-bit integer run-time statistics.
7027 Keeping this information centrally means that there is a unified way for
7028 the user to obtain data on all subsystems, and individual subsystems do
7029 not have to always include a custom data export method for performance
7030 metrics and other statistics. For example, the TRANSPORT system uses
7031 STATISTICS to update information about the number of directly connected
7032 peers and the bandwidth that has been consumed by the various plugins.
7033 This information is valuable for diagnosing connectivity and performance
7036 Following the GNUnet service architecture, the STATISTICS subsystem is
7037 divided into an API which is exposed through the header
7038 @strong{gnunet_statistics_service.h} and the STATISTICS service
7039 @strong{gnunet-service-statistics}. The @strong{gnunet-statistics}
7040 command-line tool can be used to obtain (and change) information about
7041 the values stored by the STATISTICS service. The STATISTICS service does
7042 not communicate with other peers.
7044 Data is stored in the STATISTICS service in the form of tuples
7045 @strong{(subsystem, name, value, persistence)}. The subsystem determines
7046 to which other GNUnet's subsystem the data belongs. name is the name
7047 through which value is associated. It uniquely identifies the record
7048 from among other records belonging to the same subsystem.
7049 In some parts of the code, the pair @strong{(subsystem, name)} is called
7050 a @strong{statistic} as it identifies the values stored in the STATISTCS
7051 service.The persistence flag determines if the record has to be preserved
7052 across service restarts. A record is said to be persistent if this flag
7053 is set for it; if not, the record is treated as a non-persistent record
7054 and it is lost after service restart. Persistent records are written to
7055 and read from the file @strong{statistics.data} before shutdown
7056 and upon startup. The file is located in the HOME directory of the peer.
7058 An anomaly of the STATISTICS service is that it does not terminate
7059 immediately upon receiving a shutdown signal if it has any clients
7060 connected to it. It waits for all the clients that are not monitors to
7061 close their connections before terminating itself.
7062 This is to prevent the loss of data during peer shutdown --- delaying the
7063 STATISTICS service shutdown helps other services to store important data
7064 to STATISTICS during shutdown.
7067 * libgnunetstatistics::
7068 * The STATISTICS Client-Service Protocol::
7071 @cindex libgnunetstatistics
7072 @node libgnunetstatistics
7073 @subsection libgnunetstatistics
7077 @strong{libgnunetstatistics} is the library containing the API for the
7078 STATISTICS subsystem. Any process requiring to use STATISTICS should use
7079 this API by to open a connection to the STATISTICS service.
7080 This is done by calling the function @code{GNUNET_STATISTICS_create()}.
7081 This function takes the subsystem's name which is trying to use STATISTICS
7082 and a configuration.
7083 All values written to STATISTICS with this connection will be placed in
7084 the section corresponding to the given subsystem's name.
7085 The connection to STATISTICS can be destroyed with the function
7086 @code{GNUNET_STATISTICS_destroy()}. This function allows for the
7087 connection to be destroyed immediately or upon transferring all
7088 pending write requests to the service.
7090 Note: STATISTICS subsystem can be disabled by setting @code{DISABLE = YES}
7091 under the @code{[STATISTICS]} section in the configuration. With such a
7092 configuration all calls to @code{GNUNET_STATISTICS_create()} return
7093 @code{NULL} as the STATISTICS subsystem is unavailable and no other
7094 functions from the API can be used.
7098 * Statistics retrieval::
7099 * Setting statistics and updating them::
7103 @node Statistics retrieval
7104 @subsubsection Statistics retrieval
7108 Once a connection to the statistics service is obtained, information
7109 about any other system which uses statistics can be retrieved with the
7110 function GNUNET_STATISTICS_get().
7111 This function takes the connection handle, the name of the subsystem
7112 whose information we are interested in (a @code{NULL} value will
7113 retrieve information of all available subsystems using STATISTICS), the
7114 name of the statistic we are interested in (a @code{NULL} value will
7115 retrieve all available statistics), a continuation callback which is
7116 called when all of requested information is retrieved, an iterator
7117 callback which is called for each parameter in the retrieved information
7118 and a closure for the aforementioned callbacks. The library then invokes
7119 the iterator callback for each value matching the request.
7121 Call to @code{GNUNET_STATISTICS_get()} is asynchronous and can be
7122 canceled with the function @code{GNUNET_STATISTICS_get_cancel()}.
7123 This is helpful when retrieving statistics takes too long and especially
7124 when we want to shutdown and cleanup everything.
7126 @node Setting statistics and updating them
7127 @subsubsection Setting statistics and updating them
7131 So far we have seen how to retrieve statistics, here we will learn how we
7132 can set statistics and update them so that other subsystems can retrieve
7135 A new statistic can be set using the function
7136 @code{GNUNET_STATISTICS_set()}.
7137 This function takes the name of the statistic and its value and a flag to
7138 make the statistic persistent.
7139 The value of the statistic should be of the type @code{uint64_t}.
7140 The function does not take the name of the subsystem; it is determined
7141 from the previous @code{GNUNET_STATISTICS_create()} invocation. If
7142 the given statistic is already present, its value is overwritten.
7144 An existing statistics can be updated, i.e its value can be increased or
7145 decreased by an amount with the function
7146 @code{GNUNET_STATISTICS_update()}.
7147 The parameters to this function are similar to
7148 @code{GNUNET_STATISTICS_set()}, except that it takes the amount to be
7149 changed as a type @code{int64_t} instead of the value.
7151 The library will combine multiple set or update operations into one
7152 message if the client performs requests at a rate that is faster than the
7153 available IPC with the STATISTICS service. Thus, the client does not have
7154 to worry about sending requests too quickly.
7157 @subsubsection Watches
7161 As interesting feature of STATISTICS lies in serving notifications
7162 whenever a statistic of our interest is modified.
7163 This is achieved by registering a watch through the function
7164 @code{GNUNET_STATISTICS_watch()}.
7165 The parameters of this function are similar to those of
7166 @code{GNUNET_STATISTICS_get()}.
7167 Changes to the respective statistic's value will then cause the given
7168 iterator callback to be called.
7169 Note: A watch can only be registered for a specific statistic. Hence
7170 the subsystem name and the parameter name cannot be @code{NULL} in a
7171 call to @code{GNUNET_STATISTICS_watch()}.
7173 A registered watch will keep notifying any value changes until
7174 @code{GNUNET_STATISTICS_watch_cancel()} is called with the same
7175 parameters that are used for registering the watch.
7177 @node The STATISTICS Client-Service Protocol
7178 @subsection The STATISTICS Client-Service Protocol
7183 * Statistics retrieval2::
7184 * Setting and updating statistics::
7185 * Watching for updates::
7188 @node Statistics retrieval2
7189 @subsubsection Statistics retrieval2
7193 To retrieve statistics, the client transmits a message of type
7194 @code{GNUNET_MESSAGE_TYPE_STATISTICS_GET} containing the given subsystem
7195 name and statistic parameter to the STATISTICS service.
7196 The service responds with a message of type
7197 @code{GNUNET_MESSAGE_TYPE_STATISTICS_VALUE} for each of the statistics
7198 parameters that match the client request for the client. The end of
7199 information retrieved is signaled by the service by sending a message of
7200 type @code{GNUNET_MESSAGE_TYPE_STATISTICS_END}.
7202 @node Setting and updating statistics
7203 @subsubsection Setting and updating statistics
7207 The subsystem name, parameter name, its value and the persistence flag are
7208 communicated to the service through the message
7209 @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}.
7211 When the service receives a message of type
7212 @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET}, it retrieves the subsystem
7213 name and checks for a statistic parameter with matching the name given in
7215 If a statistic parameter is found, the value is overwritten by the new
7216 value from the message; if not found then a new statistic parameter is
7217 created with the given name and value.
7219 In addition to just setting an absolute value, it is possible to perform a
7220 relative update by sending a message of type
7221 @code{GNUNET_MESSAGE_TYPE_STATISTICS_SET} with an update flag
7222 (@code{GNUNET_STATISTICS_SETFLAG_RELATIVE}) signifying that the value in
7223 the message should be treated as an update value.
7225 @node Watching for updates
7226 @subsubsection Watching for updates
7230 The function registers the watch at the service by sending a message of
7231 type @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH}. The service then sends
7232 notifications through messages of type
7233 @code{GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE} whenever the statistic
7234 parameter's value is changed.
7237 @cindex Distributed Hash Table
7238 @node Distributed Hash Table (DHT)
7239 @section Distributed Hash Table (DHT)
7243 GNUnet includes a generic distributed hash table that can be used by
7244 developers building P2P applications in the framework.
7245 This section documents high-level features and how developers are
7246 expected to use the DHT.
7247 We have a research paper detailing how the DHT works.
7248 Also, Nate's thesis includes a detailed description and performance
7249 analysis (in chapter 6).
7251 Key features of GNUnet's DHT include:
7254 @item stores key-value pairs with values up to (approximately) 63k in size
7255 @item works with many underlay network topologies (small-world, random
7256 graph), underlay does not need to be a full mesh / clique
7257 @item support for extended queries (more than just a simple 'key'),
7258 filtering duplicate replies within the network (bloomfilter) and content
7259 validation (for details, please read the subsection on the block library)
7260 @item can (optionally) return paths taken by the PUT and GET operations
7262 @item provides content replication to handle churn
7265 GNUnet's DHT is randomized and unreliable. Unreliable means that there is
7266 no strict guarantee that a value stored in the DHT is always
7267 found --- values are only found with high probability.
7268 While this is somewhat true in all P2P DHTs, GNUnet developers should be
7269 particularly wary of this fact (this will help you write secure,
7270 fault-tolerant code). Thus, when writing any application using the DHT,
7271 you should always consider the possibility that a value stored in the
7272 DHT by you or some other peer might simply not be returned, or returned
7273 with a significant delay.
7274 Your application logic must be written to tolerate this (naturally, some
7275 loss of performance or quality of service is expected in this case).
7278 * Block library and plugins::
7280 * The DHT Client-Service Protocol::
7281 * The DHT Peer-to-Peer Protocol::
7284 @node Block library and plugins
7285 @subsection Block library and plugins
7290 * What is a Block?::
7291 * The API of libgnunetblock::
7297 @node What is a Block?
7298 @subsubsection What is a Block?
7302 Blocks are small (< 63k) pieces of data stored under a key (struct
7303 GNUNET_HashCode). Blocks have a type (enum GNUNET_BlockType) which defines
7304 their data format. Blocks are used in GNUnet as units of static data
7305 exchanged between peers and stored (or cached) locally.
7306 Uses of blocks include file-sharing (the files are broken up into blocks),
7307 the VPN (DNS information is stored in blocks) and the DHT (all
7308 information in the DHT and meta-information for the maintenance of the
7309 DHT are both stored using blocks).
7310 The block subsystem provides a few common functions that must be
7311 available for any type of block.
7313 @cindex libgnunetblock API
7314 @node The API of libgnunetblock
7315 @subsubsection The API of libgnunetblock
7319 The block library requires for each (family of) block type(s) a block
7320 plugin (implementing @file{gnunet_block_plugin.h}) that provides basic
7321 functions that are needed by the DHT (and possibly other subsystems) to
7323 These block plugins are typically implemented within their respective
7325 The main block library is then used to locate, load and query the
7326 appropriate block plugin.
7327 Which plugin is appropriate is determined by the block type (which is
7328 just a 32-bit integer). Block plugins contain code that specifies which
7329 block types are supported by a given plugin. The block library loads all
7330 block plugins that are installed at the local peer and forwards the
7331 application request to the respective plugin.
7333 The central functions of the block APIs (plugin and main library) are to
7334 allow the mapping of blocks to their respective key (if possible) and the
7335 ability to check that a block is well-formed and matches a given
7336 request (again, if possible).
7337 This way, GNUnet can avoid storing invalid blocks, storing blocks under
7338 the wrong key and forwarding blocks in response to a query that they do
7341 One key function of block plugins is that it allows GNUnet to detect
7342 duplicate replies (via the Bloom filter). All plugins MUST support
7343 detecting duplicate replies (by adding the current response to the
7344 Bloom filter and rejecting it if it is encountered again).
7345 If a plugin fails to do this, responses may loop in the network.
7348 @subsubsection Queries
7351 The query format for any block in GNUnet consists of four main components.
7352 First, the type of the desired block must be specified. Second, the query
7353 must contain a hash code. The hash code is used for lookups in hash
7354 tables and databases and must not be unique for the block (however, if
7355 possible a unique hash should be used as this would be best for
7357 Third, an optional Bloom filter can be specified to exclude known results;
7358 replies that hash to the bits set in the Bloom filter are considered
7359 invalid. False-positives can be eliminated by sending the same query
7360 again with a different Bloom filter mutator value, which parameterizes
7361 the hash function that is used.
7362 Finally, an optional application-specific "eXtended query" (xquery) can
7363 be specified to further constrain the results. It is entirely up to
7364 the type-specific plugin to determine whether or not a given block
7365 matches a query (type, hash, Bloom filter, and xquery).
7366 Naturally, not all xquery's are valid and some types of blocks may not
7367 support Bloom filters either, so the plugin also needs to check if the
7368 query is valid in the first place.
7370 Depending on the results from the plugin, the DHT will then discard the
7371 (invalid) query, forward the query, discard the (invalid) reply, cache the
7372 (valid) reply, and/or forward the (valid and non-duplicate) reply.
7375 @subsubsection Sample Code
7379 The source code in @strong{plugin_block_test.c} is a good starting point
7380 for new block plugins --- it does the minimal work by implementing a
7381 plugin that performs no validation at all.
7382 The respective @strong{Makefile.am} shows how to build and install a
7386 @subsubsection Conclusion2
7390 In conclusion, GNUnet subsystems that want to use the DHT need to define a
7391 block format and write a plugin to match queries and replies. For testing,
7392 the @code{GNUNET_BLOCK_TYPE_TEST} block type can be used; it accepts
7393 any query as valid and any reply as matching any query.
7394 This type is also used for the DHT command line tools.
7395 However, it should NOT be used for normal applications due to the lack
7396 of error checking that results from this primitive implementation.
7398 @cindex libgnunetdht
7400 @subsection libgnunetdht
7404 The DHT API itself is pretty simple and offers the usual GET and PUT
7405 functions that work as expected. The specified block type refers to the
7406 block library which allows the DHT to run application-specific logic for
7407 data stored in the network.
7414 * DHT Routing Options::
7422 When using GET, the main consideration for developers (other than the
7423 block library) should be that after issuing a GET, the DHT will
7424 continuously cause (small amounts of) network traffic until the operation
7425 is explicitly canceled.
7426 So GET does not simply send out a single network request once; instead,
7427 the DHT will continue to search for data. This is needed to achieve good
7428 success rates and also handles the case where the respective PUT
7429 operation happens after the GET operation was started.
7430 Developers should not cancel an existing GET operation and then
7431 explicitly re-start it to trigger a new round of network requests;
7432 this is simply inefficient, especially as the internal automated version
7433 can be more efficient, for example by filtering results in the network
7434 that have already been returned.
7436 If an application that performs a GET request has a set of replies that it
7437 already knows and would like to filter, it can call@
7438 @code{GNUNET_DHT_get_filter_known_results} with an array of hashes over
7439 the respective blocks to tell the DHT that these results are not
7441 This way, the DHT will filter the respective blocks using the block
7442 library in the network, which may result in a significant reduction in
7443 bandwidth consumption.
7450 @c inconsistent use of ``must'' above it's written ``MUST''
7451 In contrast to GET operations, developers @strong{must} manually re-run
7452 PUT operations periodically (if they intend the content to continue to be
7453 available). Content stored in the DHT expires or might be lost due to
7455 Furthermore, GNUnet's DHT typically requires multiple rounds of PUT
7456 operations before a key-value pair is consistently available to all
7457 peers (the DHT randomizes paths and thus storage locations, and only
7458 after multiple rounds of PUTs there will be a sufficient number of
7459 replicas in large DHTs). An explicit PUT operation using the DHT API will
7460 only cause network traffic once, so in order to ensure basic availability
7461 and resistance to churn (and adversaries), PUTs must be repeated.
7462 While the exact frequency depends on the application, a rule of thumb is
7463 that there should be at least a dozen PUT operations within the content
7464 lifetime. Content in the DHT typically expires after one day, so
7465 DHT PUT operations should be repeated at least every 1-2 hours.
7468 @subsubsection MONITOR
7472 The DHT API also allows applications to monitor messages crossing the
7474 The types of messages used by the DHT are GET, PUT and RESULT messages.
7475 Using the monitoring API, applications can choose to monitor these
7476 requests, possibly limiting themselves to requests for a particular block
7479 The monitoring API is not only useful for diagnostics, it can also be
7480 used to trigger application operations based on PUT operations.
7481 For example, an application may use PUTs to distribute work requests to
7483 The workers would then monitor for PUTs that give them work, instead of
7484 looking for work using GET operations.
7485 This can be beneficial, especially if the workers have no good way to
7486 guess the keys under which work would be stored.
7487 Naturally, additional protocols might be needed to ensure that the desired
7488 number of workers will process the distributed workload.
7490 @node DHT Routing Options
7491 @subsubsection DHT Routing Options
7495 There are two important options for GET and PUT requests:
7498 @item GNUNET_DHT_RO_DEMULITPLEX_EVERYWHERE This option means that all
7499 peers should process the request, even if their peer ID is not closest to
7500 the key. For a PUT request, this means that all peers that a request
7501 traverses may make a copy of the data.
7502 Similarly for a GET request, all peers will check their local database
7503 for a result. Setting this option can thus significantly improve caching
7504 and reduce bandwidth consumption --- at the expense of a larger DHT
7505 database. If in doubt, we recommend that this option should be used.
7506 @item GNUNET_DHT_RO_RECORD_ROUTE This option instructs the DHT to record
7507 the path that a GET or a PUT request is taking through the overlay
7508 network. The resulting paths are then returned to the application with
7509 the respective result. This allows the receiver of a result to construct
7510 a path to the originator of the data, which might then be used for
7511 routing. Naturally, setting this option requires additional bandwidth
7512 and disk space, so applications should only set this if the paths are
7513 needed by the application logic.
7514 @item GNUNET_DHT_RO_FIND_PEER This option is an internal option used by
7515 the DHT's peer discovery mechanism and should not be used by applications.
7516 @item GNUNET_DHT_RO_BART This option is currently not implemented. It may
7517 in the future offer performance improvements for clique topologies.
7520 @node The DHT Client-Service Protocol
7521 @subsection The DHT Client-Service Protocol
7526 * PUTting data into the DHT::
7527 * GETting data from the DHT::
7528 * Monitoring the DHT::
7531 @node PUTting data into the DHT
7532 @subsubsection PUTting data into the DHT
7536 To store (PUT) data into the DHT, the client sends a
7537 @code{struct GNUNET_DHT_ClientPutMessage} to the service.
7538 This message specifies the block type, routing options, the desired
7539 replication level, the expiration time, key,
7540 value and a 64-bit unique ID for the operation. The service responds with
7541 a @code{struct GNUNET_DHT_ClientPutConfirmationMessage} with the same
7542 64-bit unique ID. Note that the service sends the confirmation as soon as
7543 it has locally processed the PUT request. The PUT may still be
7544 propagating through the network at this time.
7546 In the future, we may want to change this to provide (limited) feedback
7547 to the client, for example if we detect that the PUT operation had no
7548 effect because the same key-value pair was already stored in the DHT.
7549 However, changing this would also require additional state and messages
7550 in the P2P interaction.
7552 @node GETting data from the DHT
7553 @subsubsection GETting data from the DHT
7557 To retrieve (GET) data from the DHT, the client sends a
7558 @code{struct GNUNET_DHT_ClientGetMessage} to the service. The message
7559 specifies routing options, a replication level (for replicating the GET,
7560 not the content), the desired block type, the key, the (optional)
7561 extended query and unique 64-bit request ID.
7563 Additionally, the client may send any number of
7564 @code{struct GNUNET_DHT_ClientGetResultSeenMessage}s to notify the
7565 service about results that the client is already aware of.
7566 These messages consist of the key, the unique 64-bit ID of the request,
7567 and an arbitrary number of hash codes over the blocks that the client is
7568 already aware of. As messages are restricted to 64k, a client that
7569 already knows more than about a thousand blocks may need to send
7570 several of these messages. Naturally, the client should transmit these
7571 messages as quickly as possible after the original GET request such that
7572 the DHT can filter those results in the network early on. Naturally, as
7573 these messages are sent after the original request, it is conceivable
7574 that the DHT service may return blocks that match those already known
7575 to the client anyway.
7577 In response to a GET request, the service will send @code{struct
7578 GNUNET_DHT_ClientResultMessage}s to the client. These messages contain the
7579 block type, expiration, key, unique ID of the request and of course the
7580 value (a block). Depending on the options set for the respective
7581 operations, the replies may also contain the path the GET and/or the PUT
7582 took through the network.
7584 A client can stop receiving replies either by disconnecting or by sending
7585 a @code{struct GNUNET_DHT_ClientGetStopMessage} which must contain the
7586 key and the 64-bit unique ID of the original request. Using an
7587 explicit "stop" message is more common as this allows a client to run
7588 many concurrent GET operations over the same connection with the DHT
7589 service --- and to stop them individually.
7591 @node Monitoring the DHT
7592 @subsubsection Monitoring the DHT
7596 To begin monitoring, the client sends a
7597 @code{struct GNUNET_DHT_MonitorStartStop} message to the DHT service.
7598 In this message, flags can be set to enable (or disable) monitoring of
7599 GET, PUT and RESULT messages that pass through a peer. The message can
7600 also restrict monitoring to a particular block type or a particular key.
7601 Once monitoring is enabled, the DHT service will notify the client about
7602 any matching event using @code{struct GNUNET_DHT_MonitorGetMessage}s for
7603 GET events, @code{struct GNUNET_DHT_MonitorPutMessage} for PUT events
7604 and @code{struct GNUNET_DHT_MonitorGetRespMessage} for RESULTs. Each of
7605 these messages contains all of the information about the event.
7607 @node The DHT Peer-to-Peer Protocol
7608 @subsection The DHT Peer-to-Peer Protocol
7613 * Routing GETs or PUTs::
7614 * PUTting data into the DHT2::
7615 * GETting data from the DHT2::
7618 @node Routing GETs or PUTs
7619 @subsubsection Routing GETs or PUTs
7623 When routing GETs or PUTs, the DHT service selects a suitable subset of
7624 neighbours for forwarding. The exact number of neighbours can be zero or
7625 more and depends on the hop counter of the query (initially zero) in
7626 relation to the (log of) the network size estimate, the desired
7627 replication level and the peer's connectivity.
7628 Depending on the hop counter and our network size estimate, the selection
7629 of the peers maybe randomized or by proximity to the key.
7630 Furthermore, requests include a set of peers that a request has already
7631 traversed; those peers are also excluded from the selection.
7633 @node PUTting data into the DHT2
7634 @subsubsection PUTting data into the DHT2
7638 To PUT data into the DHT, the service sends a @code{struct PeerPutMessage}
7639 of type @code{GNUNET_MESSAGE_TYPE_DHT_P2P_PUT} to the respective
7641 In addition to the usual information about the content (type, routing
7642 options, desired replication level for the content, expiration time, key
7643 and value), the message contains a fixed-size Bloom filter with
7644 information about which peers (may) have already seen this request.
7645 This Bloom filter is used to ensure that DHT messages never loop back to
7646 a peer that has already processed the request.
7647 Additionally, the message includes the current hop counter and, depending
7648 on the routing options, the message may include the full path that the
7649 message has taken so far.
7650 The Bloom filter should already contain the identity of the previous hop;
7651 however, the path should not include the identity of the previous hop and
7652 the receiver should append the identity of the sender to the path, not
7653 its own identity (this is done to reduce bandwidth).
7655 @node GETting data from the DHT2
7656 @subsubsection GETting data from the DHT2
7660 A peer can search the DHT by sending @code{struct PeerGetMessage}s of type
7661 @code{GNUNET_MESSAGE_TYPE_DHT_P2P_GET} to other peers. In addition to the
7662 usual information about the request (type, routing options, desired
7663 replication level for the request, the key and the extended query), a GET
7664 request also contains a hop counter, a Bloom filter over the peers
7665 that have processed the request already and depending on the routing
7666 options the full path traversed by the GET.
7667 Finally, a GET request includes a variable-size second Bloom filter and a
7668 so-called Bloom filter mutator value which together indicate which
7669 replies the sender has already seen. During the lookup, each block that
7670 matches they block type, key and extended query is additionally subjected
7671 to a test against this Bloom filter.
7672 The block plugin is expected to take the hash of the block and combine it
7673 with the mutator value and check if the result is not yet in the Bloom
7674 filter. The originator of the query will from time to time modify the
7675 mutator to (eventually) allow false-positives filtered by the Bloom filter
7678 Peers that receive a GET request perform a local lookup (depending on
7679 their proximity to the key and the query options) and forward the request
7681 They then remember the request (including the Bloom filter for blocking
7682 duplicate results) and when they obtain a matching, non-filtered response
7683 a @code{struct PeerResultMessage} of type
7684 @code{GNUNET_MESSAGE_TYPE_DHT_P2P_RESULT} is forwarded to the previous
7686 Whenever a result is forwarded, the block plugin is used to update the
7687 Bloom filter accordingly, to ensure that the same result is never
7688 forwarded more than once.
7689 The DHT service may also cache forwarded results locally if the
7690 "CACHE_RESULTS" option is set to "YES" in the configuration.
7693 @cindex GNU Name System
7694 @node GNU Name System (GNS)
7695 @section GNU Name System (GNS)
7699 The GNU Name System (GNS) is a decentralized database that enables users
7700 to securely resolve names to values.
7701 Names can be used to identify other users (for example, in social
7702 networking), or network services (for example, VPN services running at a
7703 peer in GNUnet, or purely IP-based services on the Internet).
7704 Users interact with GNS by typing in a hostname that ends in a
7705 top-level domain that is configured in the ``GNS'' section, matches
7706 an identity of the user or ends in a Base32-encoded public key.
7708 Videos giving an overview of most of the GNS and the motivations behind
7709 it is available here and here.
7710 The remainder of this chapter targets developers that are familiar with
7711 high level concepts of GNS as presented in these talks.
7712 @c TODO: Add links to here and here and to these.
7714 GNS-aware applications should use the GNS resolver to obtain the
7715 respective records that are stored under that name in GNS.
7716 Each record consists of a type, value, expiration time and flags.
7718 The type specifies the format of the value. Types below 65536 correspond
7719 to DNS record types, larger values are used for GNS-specific records.
7720 Applications can define new GNS record types by reserving a number and
7721 implementing a plugin (which mostly needs to convert the binary value
7722 representation to a human-readable text format and vice-versa).
7723 The expiration time specifies how long the record is to be valid.
7724 The GNS API ensures that applications are only given non-expired values.
7725 The flags are typically irrelevant for applications, as GNS uses them
7726 internally to control visibility and validity of records.
7728 Records are stored along with a signature.
7729 The signature is generated using the private key of the authoritative
7730 zone. This allows any GNS resolver to verify the correctness of a
7733 Internally, GNS uses the NAMECACHE to cache information obtained from
7734 other users, the NAMESTORE to store information specific to the local
7735 users, and the DHT to exchange data between users.
7736 A plugin API is used to enable applications to define new GNS
7741 * libgnunetgnsrecord::
7743 * The GNS Client-Service Protocol::
7744 * Hijacking the DNS-Traffic using gnunet-service-dns::
7745 * Serving DNS lookups via GNS on W32::
7749 @subsection libgnunetgns
7753 The GNS API itself is extremely simple. Clients first connect to the
7754 GNS service using @code{GNUNET_GNS_connect}.
7755 They can then perform lookups using @code{GNUNET_GNS_lookup} or cancel
7756 pending lookups using @code{GNUNET_GNS_lookup_cancel}.
7757 Once finished, clients disconnect using @code{GNUNET_GNS_disconnect}.
7760 * Looking up records::
7761 * Accessing the records::
7762 * Creating records::
7766 @node Looking up records
7767 @subsubsection Looking up records
7771 @code{GNUNET_GNS_lookup} takes a number of arguments:
7774 @item handle This is simply the GNS connection handle from
7775 @code{GNUNET_GNS_connect}.
7776 @item name The client needs to specify the name to
7777 be resolved. This can be any valid DNS or GNS hostname.
7778 @item zone The client
7779 needs to specify the public key of the GNS zone against which the
7780 resolution should be done.
7781 Note that a key must be provided, the client should
7782 look up plausible values using its configuration,
7783 the identity service and by attempting to interpret the
7784 TLD as a base32-encoded public key.
7785 @item type This is the desired GNS or DNS record type
7786 to look for. While all records for the given name will be returned, this
7787 can be important if the client wants to resolve record types that
7788 themselves delegate resolution, such as CNAME, PKEY or GNS2DNS.
7789 Resolving a record of any of these types will only work if the respective
7790 record type is specified in the request, as the GNS resolver will
7791 otherwise follow the delegation and return the records from the
7792 respective destination, instead of the delegating record.
7793 @item only_cached This argument should typically be set to
7794 @code{GNUNET_NO}. Setting it to @code{GNUNET_YES} disables resolution via
7795 the overlay network.
7796 @item shorten_zone_key If GNS encounters new names during resolution,
7797 their respective zones can automatically be learned and added to the
7798 "shorten zone". If this is desired, clients must pass the private key of
7799 the shorten zone. If NULL is passed, shortening is disabled.
7800 @item proc This argument identifies
7801 the function to call with the result. It is given proc_cls, the number of
7802 records found (possibly zero) and the array of the records as arguments.
7803 proc will only be called once. After proc,> has been called, the lookup
7804 must no longer be canceled.
7805 @item proc_cls The closure for proc.
7808 @node Accessing the records
7809 @subsubsection Accessing the records
7813 The @code{libgnunetgnsrecord} library provides an API to manipulate the
7814 GNS record array that is given to proc. In particular, it offers
7815 functions such as converting record values to human-readable
7816 strings (and back). However, most @code{libgnunetgnsrecord} functions are
7817 not interesting to GNS client applications.
7819 For DNS records, the @code{libgnunetdnsparser} library provides
7820 functions for parsing (and serializing) common types of DNS records.
7822 @node Creating records
7823 @subsubsection Creating records
7827 Creating GNS records is typically done by building the respective record
7828 information (possibly with the help of @code{libgnunetgnsrecord} and
7829 @code{libgnunetdnsparser}) and then using the @code{libgnunetnamestore} to
7830 publish the information. The GNS API is not involved in this
7834 @subsubsection Future work
7838 In the future, we want to expand @code{libgnunetgns} to allow
7839 applications to observe shortening operations performed during GNS
7840 resolution, for example so that users can receive visual feedback when
7843 @node libgnunetgnsrecord
7844 @subsection libgnunetgnsrecord
7848 The @code{libgnunetgnsrecord} library is used to manipulate GNS
7849 records (in plaintext or in their encrypted format).
7850 Applications mostly interact with @code{libgnunetgnsrecord} by using the
7851 functions to convert GNS record values to strings or vice-versa, or to
7852 lookup a GNS record type number by name (or vice-versa).
7853 The library also provides various other functions that are mostly
7854 used internally within GNS, such as converting keys to names, checking for
7855 expiration, encrypting GNS records to GNS blocks, verifying GNS block
7856 signatures and decrypting GNS records from GNS blocks.
7858 We will now discuss the four commonly used functions of the API.@
7859 @code{libgnunetgnsrecord} does not perform these operations itself,
7860 but instead uses plugins to perform the operation.
7861 GNUnet includes plugins to support common DNS record types as well as
7862 standard GNS record types.
7869 @node Value handling
7870 @subsubsection Value handling
7874 @code{GNUNET_GNSRECORD_value_to_string} can be used to convert
7875 the (binary) representation of a GNS record value to a human readable,
7876 0-terminated UTF-8 string.
7877 NULL is returned if the specified record type is not supported by any
7880 @code{GNUNET_GNSRECORD_string_to_value} can be used to try to convert a
7881 human readable string to the respective (binary) representation of
7885 @subsubsection Type handling
7889 @code{GNUNET_GNSRECORD_typename_to_number} can be used to obtain the
7890 numeric value associated with a given typename. For example, given the
7891 typename "A" (for DNS A reocrds), the function will return the number 1.
7892 A list of common DNS record types is
7893 @uref{http://en.wikipedia.org/wiki/List_of_DNS_record_types, here}.
7894 Note that not all DNS record types are supported by GNUnet GNSRECORD
7895 plugins at this time.
7897 @code{GNUNET_GNSRECORD_number_to_typename} can be used to obtain the
7898 typename associated with a given numeric value.
7899 For example, given the type number 1, the function will return the
7903 @subsection GNS plugins
7907 Adding a new GNS record type typically involves writing (or extending) a
7908 GNSRECORD plugin. The plugin needs to implement the
7909 @code{gnunet_gnsrecord_plugin.h} API which provides basic functions that
7910 are needed by GNSRECORD to convert typenames and values of the respective
7911 record type to strings (and back).
7912 These gnsrecord plugins are typically implemented within their respective
7914 Examples for such plugins can be found in the GNSRECORD, GNS and
7915 CONVERSATION subsystems.
7917 The @code{libgnunetgnsrecord} library is then used to locate, load and
7918 query the appropriate gnsrecord plugin.
7919 Which plugin is appropriate is determined by the record type (which is
7920 just a 32-bit integer). The @code{libgnunetgnsrecord} library loads all
7921 block plugins that are installed at the local peer and forwards the
7922 application request to the plugins. If the record type is not
7923 supported by the plugin, it should simply return an error code.
7925 The central functions of the block APIs (plugin and main library) are the
7926 same four functions for converting between values and strings, and
7927 typenames and numbers documented in the previous subsection.
7929 @node The GNS Client-Service Protocol
7930 @subsection The GNS Client-Service Protocol
7933 The GNS client-service protocol consists of two simple messages, the
7934 @code{LOOKUP} message and the @code{LOOKUP_RESULT}. Each @code{LOOKUP}
7935 message contains a unique 32-bit identifier, which will be included in the
7936 corresponding response. Thus, clients can send many lookup requests in
7937 parallel and receive responses out-of-order.
7938 A @code{LOOKUP} request also includes the public key of the GNS zone,
7939 the desired record type and fields specifying whether shortening is
7940 enabled or networking is disabled. Finally, the @code{LOOKUP} message
7941 includes the name to be resolved.
7943 The response includes the number of records and the records themselves
7944 in the format created by @code{GNUNET_GNSRECORD_records_serialize}.
7945 They can thus be deserialized using
7946 @code{GNUNET_GNSRECORD_records_deserialize}.
7948 @node Hijacking the DNS-Traffic using gnunet-service-dns
7949 @subsection Hijacking the DNS-Traffic using gnunet-service-dns
7953 This section documents how the gnunet-service-dns (and the
7954 gnunet-helper-dns) intercepts DNS queries from the local system.
7955 This is merely one method for how we can obtain GNS queries.
7956 It is also possible to change @code{resolv.conf} to point to a machine
7957 running @code{gnunet-dns2gns} or to modify libc's name system switch
7958 (NSS) configuration to include a GNS resolution plugin.
7959 The method described in this chapter is more of a last-ditch catch-all
7962 @code{gnunet-service-dns} enables intercepting DNS traffic using policy
7964 We MARK every outgoing DNS-packet if it was not sent by our application.
7965 Using a second routing table in the Linux kernel these marked packets are
7966 then routed through our virtual network interface and can thus be
7969 Our application then reads the query and decides how to handle it.
7970 If the query can be addressed via GNS, it is passed to
7971 @code{gnunet-service-gns} and resolved internally using GNS.
7972 In the future, a reverse query for an address of the configured virtual
7973 network could be answered with records kept about previous forward
7975 Queries that are not hijacked by some application using the DNS service
7976 will be sent to the original recipient.
7977 The answer to the query will always be sent back through the virtual
7978 interface with the original nameserver as source address.
7982 * Network Setup Details::
7985 @node Network Setup Details
7986 @subsubsection Network Setup Details
7990 The DNS interceptor adds the following rules to the Linux kernel:
7992 iptables -t mangle -I OUTPUT 1 -p udp --sport $LOCALPORT --dport 53 \
7993 -j ACCEPT iptables -t mangle -I OUTPUT 2 -p udp --dport 53 -j MARK \
7994 --set-mark 3 ip rule add fwmark 3 table2 ip route add default via \
7998 @c FIXME: Rewrite to reflect display which is no longer content by line
7999 @c FIXME: due to the < 74 characters limit.
8000 Line 1 makes sure that all packets coming from a port our application
8001 opened beforehand (@code{$LOCALPORT}) will be routed normally.
8002 Line 2 marks every other packet to a DNS-Server with mark 3 (chosen
8003 arbitrarily). The third line adds a routing policy based on this mark
8004 3 via the routing table.
8006 @node Serving DNS lookups via GNS on W32
8007 @subsection Serving DNS lookups via GNS on W32
8011 This section documents how the libw32nsp (and
8012 gnunet-gns-helper-service-w32) do DNS resolutions of DNS queries on the
8013 local system. This only applies to GNUnet running on W32.
8015 W32 has a concept of "Namespaces" and "Namespace providers".
8016 These are used to present various name systems to applications in a
8018 Namespaces include DNS, mDNS, NLA and others. For each namespace any
8019 number of providers could be registered, and they are queried in an order
8020 of priority (which is adjustable).
8022 Applications can resolve names by using WSALookupService*() family of
8025 However, these are WSA-only facilities. Common BSD socket functions for
8026 namespace resolutions are gethostbyname and getaddrinfo (among others).
8027 These functions are implemented internally (by default - by mswsock,
8028 which also implements the default DNS provider) as wrappers around
8029 WSALookupService*() functions (see "Sample Code for a Service Provider"
8032 On W32 GNUnet builds a libw32nsp - a namespace provider, which can then be
8033 installed into the system by using w32nsp-install (and uninstalled by
8034 w32nsp-uninstall), as described in "Installation Handbook".
8036 libw32nsp is very simple and has almost no dependencies. As a response to
8037 NSPLookupServiceBegin(), it only checks that the provider GUID passed to
8038 it by the caller matches GNUnet DNS Provider GUID,
8040 gnunet-gns-helper-service-w32 at 127.0.0.1:5353 (hardcoded) and sends the
8041 name resolution request there, returning the connected socket to the
8044 When the caller invokes NSPLookupServiceNext(), libw32nsp reads a
8045 completely formed reply from that socket, unmarshalls it, then gives
8046 it back to the caller.
8048 At the moment gnunet-gns-helper-service-w32 is implemented to ever give
8049 only one reply, and subsequent calls to NSPLookupServiceNext() will fail
8050 with WSA_NODATA (first call to NSPLookupServiceNext() might also fail if
8051 GNS failed to find the name, or there was an error connecting to it).
8053 gnunet-gns-helper-service-w32 does most of the processing:
8056 @item Maintains a connection to GNS.
8057 @item Reads GNS config and loads appropriate keys.
8058 @item Checks service GUID and decides on the type of record to look up,
8059 refusing to make a lookup outright when unsupported service GUID is
8061 @item Launches the lookup
8064 When lookup result arrives, gnunet-gns-helper-service-w32 forms a complete
8065 reply (including filling a WSAQUERYSETW structure and, possibly, a binary
8066 blob with a hostent structure for gethostbyname() client), marshalls it,
8067 and sends it back to libw32nsp. If no records were found, it sends an
8070 This works for most normal applications that use gethostbyname() or
8071 getaddrinfo() to resolve names, but fails to do anything with
8072 applications that use alternative means of resolving names (such as
8073 sending queries to a DNS server directly by themselves).
8074 This includes some of well known utilities, like "ping" and "nslookup".
8076 @cindex GNS Namecache
8078 @section GNS Namecache
8082 The NAMECACHE subsystem is responsible for caching (encrypted) resolution
8083 results of the GNU Name System (GNS). GNS makes zone information available
8084 to other users via the DHT. However, as accessing the DHT for every
8085 lookup is expensive (and as the DHT's local cache is lost whenever the
8086 peer is restarted), GNS uses the NAMECACHE as a more persistent cache for
8088 Thus, instead of always looking up every name in the DHT, GNS first
8089 checks if the result is already available locally in the NAMECACHE.
8090 Only if there is no result in the NAMECACHE, GNS queries the DHT.
8091 The NAMECACHE stores data in the same (encrypted) format as the DHT.
8092 It thus makes no sense to iterate over all items in the
8093 NAMECACHE --- the NAMECACHE does not have a way to provide the keys
8094 required to decrypt the entries.
8096 Blocks in the NAMECACHE share the same expiration mechanism as blocks in
8097 the DHT --- the block expires wheneever any of the records in
8098 the (encrypted) block expires.
8099 The expiration time of the block is the only information stored in
8100 plaintext. The NAMECACHE service internally performs all of the required
8101 work to expire blocks, clients do not have to worry about this.
8102 Also, given that NAMECACHE stores only GNS blocks that local users
8103 requested, there is no configuration option to limit the size of the
8104 NAMECACHE. It is assumed to be always small enough (a few MB) to fit on
8107 The NAMECACHE supports the use of different database backends via a
8111 * libgnunetnamecache::
8112 * The NAMECACHE Client-Service Protocol::
8113 * The NAMECACHE Plugin API::
8116 @node libgnunetnamecache
8117 @subsection libgnunetnamecache
8121 The NAMECACHE API consists of five simple functions. First, there is
8122 @code{GNUNET_NAMECACHE_connect} to connect to the NAMECACHE service.
8123 This returns the handle required for all other operations on the
8124 NAMECACHE. Using @code{GNUNET_NAMECACHE_block_cache} clients can insert a
8125 block into the cache.
8126 @code{GNUNET_NAMECACHE_lookup_block} can be used to lookup blocks that
8127 were stored in the NAMECACHE. Both operations can be canceled using
8128 @code{GNUNET_NAMECACHE_cancel}. Note that canceling a
8129 @code{GNUNET_NAMECACHE_block_cache} operation can result in the block
8130 being stored in the NAMECACHE --- or not. Cancellation primarily ensures
8131 that the continuation function with the result of the operation will no
8133 Finally, @code{GNUNET_NAMECACHE_disconnect} closes the connection to the
8136 The maximum size of a block that can be stored in the NAMECACHE is
8137 @code{GNUNET_NAMECACHE_MAX_VALUE_SIZE}, which is defined to be 63 kB.
8139 @node The NAMECACHE Client-Service Protocol
8140 @subsection The NAMECACHE Client-Service Protocol
8144 All messages in the NAMECACHE IPC protocol start with the
8145 @code{struct GNUNET_NAMECACHE_Header} which adds a request
8146 ID (32-bit integer) to the standard message header.
8147 The request ID is used to match requests with the
8148 respective responses from the NAMECACHE, as they are allowed to happen
8158 @subsubsection Lookup
8162 The @code{struct LookupBlockMessage} is used to lookup a block stored in
8164 It contains the query hash. The NAMECACHE always responds with a
8165 @code{struct LookupBlockResponseMessage}. If the NAMECACHE has no
8166 response, it sets the expiration time in the response to zero.
8167 Otherwise, the response is expected to contain the expiration time, the
8168 ECDSA signature, the derived key and the (variable-size) encrypted data
8172 @subsubsection Store
8176 The @code{struct BlockCacheMessage} is used to cache a block in the
8178 It has the same structure as the @code{struct LookupBlockResponseMessage}.
8179 The service responds with a @code{struct BlockCacheResponseMessage} which
8180 contains the result of the operation (success or failure).
8181 In the future, we might want to make it possible to provide an error
8184 @node The NAMECACHE Plugin API
8185 @subsection The NAMECACHE Plugin API
8188 The NAMECACHE plugin API consists of two functions, @code{cache_block} to
8189 store a block in the database, and @code{lookup_block} to lookup a block
8199 @subsubsection Lookup2
8203 The @code{lookup_block} function is expected to return at most one block
8204 to the iterator, and return @code{GNUNET_NO} if there were no non-expired
8206 If there are multiple non-expired results in the cache, the lookup is
8207 supposed to return the result with the largest expiration time.
8210 @subsubsection Store2
8214 The @code{cache_block} function is expected to try to store the block in
8215 the database, and return @code{GNUNET_SYSERR} if this was not possible
8217 Furthermore, @code{cache_block} is expected to implicitly perform cache
8218 maintenance and purge blocks from the cache that have expired. Note that
8219 @code{cache_block} might encounter the case where the database already has
8220 another block stored under the same key. In this case, the plugin must
8221 ensure that the block with the larger expiration time is preserved.
8222 Obviously, this can done either by simply adding new blocks and selecting
8223 for the most recent expiration time during lookup, or by checking which
8224 block is more recent during the store operation.
8226 @cindex REVOCATION Subsystem
8227 @node REVOCATION Subsystem
8228 @section REVOCATION Subsystem
8231 The REVOCATION subsystem is responsible for key revocation of Egos.
8232 If a user learns that theis private key has been compromised or has lost
8233 it, they can use the REVOCATION system to inform all of the other users
8234 that their private key is no longer valid.
8235 The subsystem thus includes ways to query for the validity of keys and to
8236 propagate revocation messages.
8240 * Revocation Message Design Requirements::
8241 * libgnunetrevocation::
8242 * The REVOCATION Client-Service Protocol::
8243 * The REVOCATION Peer-to-Peer Protocol::
8247 @subsection Dissemination
8251 When a revocation is performed, the revocation is first of all
8252 disseminated by flooding the overlay network.
8253 The goal is to reach every peer, so that when a peer needs to check if a
8254 key has been revoked, this will be purely a local operation where the
8255 peer looks at its local revocation list. Flooding the network is also the
8256 most robust form of key revocation --- an adversary would have to control
8257 a separator of the overlay graph to restrict the propagation of the
8258 revocation message. Flooding is also very easy to implement --- peers that
8259 receive a revocation message for a key that they have never seen before
8260 simply pass the message to all of their neighbours.
8262 Flooding can only distribute the revocation message to peers that are
8264 In order to notify peers that join the network later, the revocation
8265 service performs efficient set reconciliation over the sets of known
8266 revocation messages whenever two peers (that both support REVOCATION
8267 dissemination) connect.
8268 The SET service is used to perform this operation efficiently.
8270 @node Revocation Message Design Requirements
8271 @subsection Revocation Message Design Requirements
8275 However, flooding is also quite costly, creating O(|E|) messages on a
8276 network with |E| edges.
8277 Thus, revocation messages are required to contain a proof-of-work, the
8278 result of an expensive computation (which, however, is cheap to verify).
8279 Only peers that have expended the CPU time necessary to provide
8280 this proof will be able to flood the network with the revocation message.
8281 This ensures that an attacker cannot simply flood the network with
8282 millions of revocation messages. The proof-of-work required by GNUnet is
8283 set to take days on a typical PC to compute; if the ability to quickly
8284 revoke a key is needed, users have the option to pre-compute revocation
8285 messages to store off-line and use instantly after their key has expired.
8287 Revocation messages must also be signed by the private key that is being
8288 revoked. Thus, they can only be created while the private key is in the
8289 possession of the respective user. This is another reason to create a
8290 revocation message ahead of time and store it in a secure location.
8292 @node libgnunetrevocation
8293 @subsection libgnunetrevocation
8297 The REVOCATION API consists of two parts, to query and to issue
8302 * Querying for revoked keys::
8303 * Preparing revocations::
8304 * Issuing revocations::
8307 @node Querying for revoked keys
8308 @subsubsection Querying for revoked keys
8312 @code{GNUNET_REVOCATION_query} is used to check if a given ECDSA public
8313 key has been revoked.
8314 The given callback will be invoked with the result of the check.
8315 The query can be canceled using @code{GNUNET_REVOCATION_query_cancel} on
8318 @node Preparing revocations
8319 @subsubsection Preparing revocations
8323 It is often desirable to create a revocation record ahead-of-time and
8324 store it in an off-line location to be used later in an emergency.
8325 This is particularly true for GNUnet revocations, where performing the
8326 revocation operation itself is computationally expensive and thus is
8327 likely to take some time.
8328 Thus, if users want the ability to perform revocations quickly in an
8329 emergency, they must pre-compute the revocation message.
8330 The revocation API enables this with two functions that are used to
8331 compute the revocation message, but not trigger the actual revocation
8334 @code{GNUNET_REVOCATION_check_pow} should be used to calculate the
8335 proof-of-work required in the revocation message. This function takes the
8336 public key, the required number of bits for the proof of work (which in
8337 GNUnet is a network-wide constant) and finally a proof-of-work number as
8339 The function then checks if the given proof-of-work number is a valid
8340 proof of work for the given public key. Clients preparing a revocation
8341 are expected to call this function repeatedly (typically with a
8342 monotonically increasing sequence of numbers of the proof-of-work number)
8343 until a given number satisfies the check.
8344 That number should then be saved for later use in the revocation
8347 @code{GNUNET_REVOCATION_sign_revocation} is used to generate the
8348 signature that is required in a revocation message.
8349 It takes the private key that (possibly in the future) is to be revoked
8350 and returns the signature.
8351 The signature can again be saved to disk for later use, which will then
8352 allow performing a revocation even without access to the private key.
8354 @node Issuing revocations
8355 @subsubsection Issuing revocations
8358 Given a ECDSA public key, the signature from @code{GNUNET_REVOCATION_sign}
8359 and the proof-of-work,
8360 @code{GNUNET_REVOCATION_revoke} can be used to perform the
8361 actual revocation. The given callback is called upon completion of the
8362 operation. @code{GNUNET_REVOCATION_revoke_cancel} can be used to stop the
8363 library from calling the continuation; however, in that case it is
8364 undefined whether or not the revocation operation will be executed.
8366 @node The REVOCATION Client-Service Protocol
8367 @subsection The REVOCATION Client-Service Protocol
8370 The REVOCATION protocol consists of four simple messages.
8372 A @code{QueryMessage} containing a public ECDSA key is used to check if a
8373 particular key has been revoked. The service responds with a
8374 @code{QueryResponseMessage} which simply contains a bit that says if the
8375 given public key is still valid, or if it has been revoked.
8377 The second possible interaction is for a client to revoke a key by
8378 passing a @code{RevokeMessage} to the service. The @code{RevokeMessage}
8379 contains the ECDSA public key to be revoked, a signature by the
8380 corresponding private key and the proof-of-work, The service responds
8381 with a @code{RevocationResponseMessage} which can be used to indicate
8382 that the @code{RevokeMessage} was invalid (i.e. proof of work incorrect),
8383 or otherwise indicates that the revocation has been processed
8386 @node The REVOCATION Peer-to-Peer Protocol
8387 @subsection The REVOCATION Peer-to-Peer Protocol
8391 Revocation uses two disjoint ways to spread revocation information among
8393 First of all, P2P gossip exchanged via CORE-level neighbours is used to
8394 quickly spread revocations to all connected peers.
8395 Second, whenever two peers (that both support revocations) connect,
8396 the SET service is used to compute the union of the respective revocation
8399 In both cases, the exchanged messages are @code{RevokeMessage}s which
8400 contain the public key that is being revoked, a matching ECDSA signature,
8401 and a proof-of-work.
8402 Whenever a peer learns about a new revocation this way, it first
8403 validates the signature and the proof-of-work, then stores it to disk
8404 (typically to a file $GNUNET_DATA_HOME/revocation.dat) and finally
8405 spreads the information to all directly connected neighbours.
8407 For computing the union using the SET service, the peer with the smaller
8408 hashed peer identity will connect (as a "client" in the two-party set
8409 protocol) to the other peer after one second (to reduce traffic spikes
8410 on connect) and initiate the computation of the set union.
8411 All revocation services use a common hash to identify the SET operation
8412 over revocation sets.
8414 The current implementation accepts revocation set union operations from
8415 all peers at any time; however, well-behaved peers should only initiate
8416 this operation once after establishing a connection to a peer with a
8417 larger hashed peer identity.
8420 @cindex FS Subsystem
8421 @node File-sharing (FS) Subsystem
8422 @section File-sharing (FS) Subsystem
8426 This chapter describes the details of how the file-sharing service works.
8427 As with all services, it is split into an API (libgnunetfs), the service
8428 process (gnunet-service-fs) and user interface(s).
8429 The file-sharing service uses the datastore service to store blocks and
8430 the DHT (and indirectly datacache) for lookups for non-anonymous
8432 Furthermore, the file-sharing service uses the block library (and the
8433 block fs plugin) for validation of DHT operations.
8435 In contrast to many other services, libgnunetfs is rather complex since
8436 the client library includes a large number of high-level abstractions;
8437 this is necessary since the Fs service itself largely only operates on
8439 The FS library is responsible for providing a file-based abstraction to
8440 applications, including directories, meta data, keyword search,
8441 verification, and so on.
8443 The method used by GNUnet to break large files into blocks and to use
8444 keyword search is called the
8445 "Encoding for Censorship Resistant Sharing" (ECRS).
8446 ECRS is largely implemented in the fs library; block validation is also
8447 reflected in the block FS plugin and the FS service.
8448 ECRS on-demand encoding is implemented in the FS service.
8450 NOTE: The documentation in this chapter is quite incomplete.
8453 * Encoding for Censorship-Resistant Sharing (ECRS)::
8454 * File-sharing persistence directory structure::
8458 @cindex Encoding for Censorship-Resistant Sharing
8459 @node Encoding for Censorship-Resistant Sharing (ECRS)
8460 @subsection Encoding for Censorship-Resistant Sharing (ECRS)
8464 When GNUnet shares files, it uses a content encoding that is called ECRS,
8465 the Encoding for Censorship-Resistant Sharing.
8466 Most of ECRS is described in the (so far unpublished) research paper
8467 attached to this page. ECRS obsoletes the previous ESED and ESED II
8468 encodings which were used in GNUnet before version 0.7.0.
8469 The rest of this page assumes that the reader is familiar with the
8470 attached paper. What follows is a description of some minor extensions
8471 that GNUnet makes over what is described in the paper.
8472 The reason why these extensions are not in the paper is that we felt
8473 that they were obvious or trivial extensions to the original scheme and
8474 thus did not warrant space in the research report.
8477 * Namespace Advertisements::
8481 @node Namespace Advertisements
8482 @subsubsection Namespace Advertisements
8485 @c %**FIXME: all zeroses -> ?
8487 An @code{SBlock} with identifier all zeros is a signed
8488 advertisement for a namespace. This special @code{SBlock} contains
8489 metadata describing the content of the namespace.
8490 Instead of the name of the identifier for a potential update, it contains
8491 the identifier for the root of the namespace.
8492 The URI should always be empty. The @code{SBlock} is signed with the
8493 content provider's RSA private key (just like any other SBlock). Peers
8494 can search for @code{SBlock}s in order to find out more about a namespace.
8497 @subsubsection KSBlocks
8501 GNUnet implements @code{KSBlocks} which are @code{KBlocks} that, instead
8502 of encrypting a CHK and metadata, encrypt an @code{SBlock} instead.
8503 In other words, @code{KSBlocks} enable GNUnet to find @code{SBlocks}
8504 using the global keyword search.
8505 Usually the encrypted @code{SBlock} is a namespace advertisement.
8506 The rationale behind @code{KSBlock}s and @code{SBlock}s is to enable
8507 peers to discover namespaces via keyword searches, and, to associate
8508 useful information with namespaces. When GNUnet finds @code{KSBlocks}
8509 during a normal keyword search, it adds the information to an internal
8510 list of discovered namespaces. Users looking for interesting namespaces
8511 can then inspect this list, reducing the need for out-of-band discovery
8513 Naturally, namespaces (or more specifically, namespace advertisements) can
8514 also be referenced from directories, but @code{KSBlock}s should make it
8515 easier to advertise namespaces for the owner of the pseudonym since they
8516 eliminate the need to first create a directory.
8518 Collections are also advertised using @code{KSBlock}s.
8520 @c https://gnunet.org/sites/default/files/ecrs.pdf
8522 @node File-sharing persistence directory structure
8523 @subsection File-sharing persistence directory structure
8527 This section documents how the file-sharing library implements
8528 persistence of file-sharing operations and specifically the resulting
8529 directory structure.
8530 This code is only active if the @code{GNUNET_FS_FLAGS_PERSISTENCE} flag
8531 was set when calling @code{GNUNET_FS_start}.
8532 In this case, the file-sharing library will try hard to ensure that all
8533 major operations (searching, downloading, publishing, unindexing) are
8534 persistent, that is, can live longer than the process itself.
8535 More specifically, an operation is supposed to live until it is
8538 If @code{GNUNET_FS_stop} is called before an operation has been stopped, a
8539 @code{SUSPEND} event is generated and then when the process calls
8540 @code{GNUNET_FS_start} next time, a @code{RESUME} event is generated.
8541 Additionally, even if an application crashes (segfault, SIGKILL, system
8542 crash) and hence @code{GNUNET_FS_stop} is never called and no
8543 @code{SUSPEND} events are generated, operations are still resumed (with
8544 @code{RESUME} events).
8545 This is implemented by constantly writing the current state of the
8546 file-sharing operations to disk.
8547 Specifically, the current state is always written to disk whenever
8548 anything significant changes (the exception are block-wise progress in
8549 publishing and unindexing, since those operations would be slowed down
8550 significantly and can be resumed cheaply even without detailed
8552 Note that if the process crashes (or is killed) during a serialization
8553 operation, FS does not guarantee that this specific operation is
8554 recoverable (no strict transactional semantics, again for performance
8555 reasons). However, all other unrelated operations should resume nicely.
8557 Since we need to serialize the state continuously and want to recover as
8558 much as possible even after crashing during a serialization operation,
8559 we do not use one large file for serialization.
8560 Instead, several directories are used for the various operations.
8561 When @code{GNUNET_FS_start} executes, the master directories are scanned
8562 for files describing operations to resume.
8563 Sometimes, these operations can refer to related operations in child
8564 directories which may also be resumed at this point.
8565 Note that corrupted files are cleaned up automatically.
8566 However, dangling files in child directories (those that are not
8567 referenced by files from the master directories) are not automatically
8570 Persistence data is kept in a directory that begins with the "STATE_DIR"
8571 prefix from the configuration file
8572 (by default, "$SERVICEHOME/persistence/") followed by the name of the
8573 client as given to @code{GNUNET_FS_start} (for example, "gnunet-gtk")
8574 followed by the actual name of the master or child directory.
8576 The names for the master directories follow the names of the operations:
8585 Each of the master directories contains names (chosen at random) for each
8586 active top-level (master) operation.
8587 Note that a download that is associated with a search result is not a
8588 top-level operation.
8590 In contrast to the master directories, the child directories are only
8591 consulted when another operation refers to them.
8592 For each search, a subdirectory (named after the master search
8593 synchronization file) contains the search results.
8594 Search results can have an associated download, which is then stored in
8595 the general "download-child" directory.
8596 Downloads can be recursive, in which case children are stored in
8597 subdirectories mirroring the structure of the recursive download
8598 (either starting in the master "download" directory or in the
8599 "download-child" directory depending on how the download was initiated).
8600 For publishing operations, the "publish-file" directory contains
8601 information about the individual files and directories that are part of
8603 However, this directory structure is flat and does not mirror the
8604 structure of the publishing operation.
8605 Note that unindex operations cannot have associated child operations.
8607 @cindex REGEX subsystem
8608 @node REGEX Subsystem
8609 @section REGEX Subsystem
8613 Using the REGEX subsystem, you can discover peers that offer a particular
8614 service using regular expressions.
8615 The peers that offer a service specify it using a regular expressions.
8616 Peers that want to patronize a service search using a string.
8617 The REGEX subsystem will then use the DHT to return a set of matching
8618 offerers to the patrons.
8620 For the technical details, we have Max's defense talk and Max's Master's
8623 @c An additional publication is under preparation and available to
8624 @c team members (in Git).
8625 @c FIXME: Where is the file? Point to it. Assuming that it's szengel2012ms
8628 * How to run the regex profiler::
8631 @node How to run the regex profiler
8632 @subsection How to run the regex profiler
8636 The gnunet-regex-profiler can be used to profile the usage of mesh/regex
8637 for a given set of regular expressions and strings.
8638 Mesh/regex allows you to announce your peer ID under a certain regex and
8639 search for peers matching a particular regex using a string.
8640 See @uref{https://gnunet.org/szengel2012ms, szengel2012ms} for a full
8643 First of all, the regex profiler uses GNUnet testbed, thus all the
8644 implications for testbed also apply to the regex profiler
8645 (for example you need password-less ssh login to the machines listed in
8648 @strong{Configuration}
8650 Moreover, an appropriate configuration file is needed.
8651 Generally you can refer to the
8652 @file{contrib/regex_profiler_infiniband.conf} file in the sourcecode
8653 of GNUnet for an example configuration.
8654 In the following paragraph the important details are highlighted.
8656 Announcing of the regular expressions is done by the
8657 gnunet-daemon-regexprofiler, therefore you have to make sure it is
8658 started, by adding it to the START_ON_DEMAND set of ARM:
8662 START_ON_DEMAND = YES
8666 Furthermore you have to specify the location of the binary:
8670 # Location of the gnunet-daemon-regexprofiler binary.
8671 BINARY = /home/szengel/gnunet/src/mesh/.libs/gnunet-daemon-regexprofiler
8672 # Regex prefix that will be applied to all regular expressions and
8674 REGEX_PREFIX = "GNVPN-0001-PAD"
8678 When running the profiler with a large scale deployment, you probably
8679 want to reduce the workload of each peer.
8680 Use the following options to do this.
8684 # Force network size estimation
8689 # Disable RC-file for Bloom filter? (for benchmarking with limited IO
8692 # Disable Bloom filter entirely
8696 # Minimize proof-of-work CPU consumption by NSE
8703 To finally run the profiler some options and the input data need to be
8704 specified on the command line.
8707 gnunet-regex-profiler -c config-file -d log-file -n num-links \
8708 -p path-compression-length -s search-delay -t matching-timeout \
8709 -a num-search-strings hosts-file policy-dir search-strings-file
8716 @item ... @code{config-file} means the configuration file created earlier.
8717 @item ... @code{log-file} is the file where to write statistics output.
8718 @item ... @code{num-links} indicates the number of random links between
8720 @item ... @code{path-compression-length} is the maximum path compression
8722 @item ... @code{search-delay} time to wait between peers finished linking
8723 and starting to match strings.
8724 @item ... @code{matching-timeout} timeout after which to cancel the
8726 @item ... @code{num-search-strings} number of strings in the
8727 search-strings-file.
8728 @item ... the @code{hosts-file} should contain a list of hosts for the
8729 testbed, one per line in the following format:
8732 @item @code{user@@host_ip:port}
8734 @item ... the @code{policy-dir} is a folder containing text files
8735 containing one or more regular expressions. A peer is started for each
8736 file in that folder and the regular expressions in the corresponding file
8737 are announced by this peer.
8738 @item ... the @code{search-strings-file} is a text file containing search
8739 strings, one in each line.
8743 You can create regular expressions and search strings for every AS in the
8744 Internet using the attached scripts. You need one of the
8745 @uref{http://data.caida.org/datasets/routing/routeviews-prefix2as/, CAIDA routeviews prefix2as}
8746 data files for this. Run
8749 create_regex.py <filename> <output path>
8753 to create the regular expressions and
8756 create_strings.py <input path> <outfile>
8760 to create a search strings file from the previously created
8761 regular expressions.
8763 @cindex REST subsystem
8764 @node REST Subsystem
8765 @section REST Subsystem
8769 Using the REST subsystem, you can expose REST-based APIs or services.
8770 The REST service is designed as a pluggable architecture.
8771 To create a new REST endpoint, simply add a library in the form
8773 The REST service will automatically load all REST plugins on startup.
8775 @strong{Configuration}
8777 The REST service can be configured in various ways.
8778 The reference config file can be found in
8779 @file{src/rest/rest.conf}:
8783 REST_ALLOW_HEADERS=Authorization,Accept,Content-Type
8785 REST_ALLOW_CREDENTIALS=true
8789 @deffn{cross-origin resource sharing} (CORS)
8791 headers that are supposed to be advertised by the rest service are
8795 * Namespace considerations::
8796 * Endpoint documentation::
8799 @node Namespace considerations
8800 @subsection Namespace considerations
8802 The @command{gnunet-rest-service} will load all plugins that are installed.
8803 As such it is important that the endpoint namespaces do not clash.
8805 For example, plugin X might expose the endpoint ``/xxx'' while plugin Y
8806 exposes endpoint ``/xxx/yyy''.
8807 This is a problem if plugin X is also supposed to handle a call
8809 Currently the REST service will not complain or warn about such clashes,
8810 so please make sure that endpoints are unambiguous.
8812 @node Endpoint documentation
8813 @subsection Endpoint documentation
8815 This is WIP. Endpoints should be documented appropriately.
8816 Preferably using annotations.