src/include/gnunet_testbed_service.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_testbed_service.h
  23  * @brief API for writing tests and creating large-scale
  24  *        emulation testbeds for GNUnet.
  25  * @author Christian Grothoff
  26  */
  27
  28 #ifndef GNUNET_TESTBED_SERVICE_H
  29 #define GNUNET_TESTBED_SERVICE_H
  30
  31 #include "gnunet_util_lib.h"
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41
  42 /**
  43  * Opaque handle to a host running experiments managed by the testbed framework.
  44  * The master process must be able to SSH to this host without password (via
  45  * ssh-agent).
  46  */
  47 struct GNUNET_TESTBED_Host;
  48
  49 /**
  50  * Opaque handle to a peer controlled by the testbed framework.  A peer runs
  51  * at a particular host.
  52  */
  53 struct GNUNET_TESTBED_Peer;
  54
  55 /**
  56  * Opaque handle to an abstract operation to be executed by the testbed framework.
  57  */
  58 struct GNUNET_TESTBED_Operation;
  59
  60 /**
  61  * Handle to interact with a GNUnet testbed controller.  Each
  62  * controller has at least one master handle which is created when the
  63  * controller is created; this master handle interacts with the
  64  * controller process, destroying it destroys the controller (by
  65  * closing stdin of the controller process).  Additionally,
  66  * controllers can interact with each other (in a P2P fashion); those
  67  * links are established via TCP/IP on the controller's service port.
  68  */
  69 struct GNUNET_TESTBED_Controller;
  70
  71 /**
  72  * Handle to a large-scale testbed that is managed at a high level.
  73  */
  74 struct GNUNET_TESTBED_Testbed;
  75
  76
  77 /**
  78  * Create a host to run peers and controllers on.
  79  *
  80  * @param hostname name of the host, use "NULL" for localhost
  81  * @param username username to use for the login; may be NULL
  82  * @param port port number to use for ssh; use 0 to let ssh decide
  83  * @return handle to the host, NULL on error
  84  */
  85 struct GNUNET_TESTBED_Host *
  86 GNUNET_TESTBED_host_create (const char *hostname,
  87                             const char *username,
  88                             uint16_t port);
  89
  90
  91
  92 /**
  93  * Create a host to run peers and controllers on.  This function is used
  94  * if a peer learns about a host via IPC between controllers (and thus
  95  * some higher-level controller has already determined the unique IDs).
  96  *
  97  * @param id global host ID assigned to the host; 0 is
  98  *        reserved to always mean 'localhost'
  99  * @param hostname name of the host, use "NULL" for localhost
 100  * @param username username to use for the login; may be NULL
 101  * @param port port number to use for ssh; use 0 to let ssh decide
 102  * @return handle to the host, NULL on error
 103  */
 104 struct GNUNET_TESTBED_Host *
 105 GNUNET_TESTBED_host_create_with_id (uint32_t id,
 106                                     const char *hostname,
 107                                     const char *username,
 108                                     uint16_t port);
 109
 110
 111 /**
 112  * Load a set of hosts from a configuration file.
 113  *
 114  * @param filename file with the host specification
 115  * @param hosts set to the hosts found in the file
 116  * @return number of hosts returned in 'hosts', 0 on error
 117  */
 118 unsigned int
 119 GNUNET_TESTBED_hosts_load_from_file (const char *filename,
 120                                      struct GNUNET_TESTBED_Host **hosts);
 121
 122
 123 /**
 124  * Destroy a host handle.  Must only be called once everything
 125  * running on that host has been stopped.
 126  *
 127  * @param host handle to destroy
 128  */
 129 void
 130 GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host);
 131
 132
 133 /**
 134  * Enumeration with (at most 64) possible event types that
 135  * can be monitored using the testbed framework.
 136  */
 137 enum GNUNET_TESTBED_EventType
 138 {
 139   /**
 140    * A peer has been started.
 141    */
 142   GNUNET_TESTBED_ET_PEER_START = 0,
 143
 144   /**
 145    * A peer has been stopped.
 146    */
 147   GNUNET_TESTBED_ET_PEER_STOP = 1,
 148
 149   /**
 150    * A connection between two peers was established.
 151    */
 152   GNUNET_TESTBED_ET_CONNECT = 2,
 153
 154   /**
 155    * A connection between two peers was torn down.
 156    */
 157   GNUNET_TESTBED_ET_DISCONNECT = 3,
 158
 159   /**
 160    * A requested testbed operation has been completed.
 161    */
 162   GNUNET_TESTBED_ET_OPERATION_FINISHED = 4,
 163
 164   /**
 165    * The 'GNUNET_TESTBED_run' operation has been completed
 166    */
 167   GNUNET_TESTBED_ET_TESTBED_ONLINE = 5
 168
 169 };
 170
 171
 172 /**
 173  * Types of information that can be requested about a peer.
 174  */
 175 enum GNUNET_TESTBED_PeerInformationType
 176 {
 177
 178   /**
 179    * Special value (not valid for requesting information)
 180    * that is used in the event struct if a 'generic' pointer
 181    * is returned (for other operations not related to this
 182    * enumeration).
 183    */
 184   GNUNET_TESTBED_PIT_GENERIC = 0,
 185
 186   /**
 187    * What host is the peer running on?  Returns a 'const struct
 188    * GNUNET_TESTBED_Host *'.  Valid until
 189    * 'GNUNET_TESTBED_operation_done' is called.
 190    */
 191   GNUNET_TESTBED_PIT_HOST,
 192
 193   /**
 194    * What configuration is the peer using?  Returns a 'const struct
 195    * GNUNET_CONFIGURATION_Handle *'.  Valid until
 196    * 'GNUNET_TESTNIG_operation_done' is called.  However, the
 197    * values may be inaccurate if the peer is reconfigured in
 198    * the meantime.
 199    */
 200   GNUNET_TESTBED_PIT_CONFIGURATION,
 201
 202   /**
 203    * What is the identity of the peer?  Returns a
 204    * 'const struct GNUNET_PeerIdentity *'.  Valid until
 205    * 'GNUNET_TESTNIG_operation_done' is called.
 206    */
 207   GNUNET_TESTBED_PIT_IDENTITY
 208
 209 };
 210
 211
 212 /**
 213  * Argument to GNUNET_TESTBED_ControllerCallback with details about
 214  * the event.
 215  */
 216 struct GNUNET_TESTBED_EventInformation
 217 {
 218
 219   /**
 220    * Type of the event.
 221    */
 222   enum GNUNET_TESTBED_EventType type;
 223
 224   /**
 225    * Details about the event.
 226    */
 227   union
 228   {
 229
 230     /**
 231      * Details about peer start event.
 232      */
 233     struct
 234     {
 235       /**
 236        * Handle for the host where the peer
 237        * was started.
 238        */
 239       struct GNUNET_TESTBED_Host *host;
 240
 241       /**
 242        * Handle for the peer that was started.
 243        */
 244       struct GNUNET_TESTBED_Peer *peer;
 245
 246     } peer_start;
 247
 248     /**
 249      * Details about peer stop event.
 250      */
 251     struct
 252     {
 253
 254       /**
 255        * Handle for the peer that was started.
 256        */
 257       struct GNUNET_TESTBED_Peer *peer;
 258
 259     } peer_stop;
 260
 261     /**
 262      * Details about connect event.
 263      */
 264     struct
 265     {
 266       /**
 267        * Handle for one of the connected peers.
 268        */
 269       struct GNUNET_TESTBED_Peer *peer1;
 270
 271       /**
 272        * Handle for one of the connected peers.
 273        */
 274       struct GNUNET_TESTBED_Peer *peer2;
 275
 276     } peer_connect;
 277
 278     /**
 279      * Details about disconnect event.
 280      */
 281     struct
 282     {
 283       /**
 284        * Handle for one of the disconnected peers.
 285        */
 286       struct GNUNET_TESTBED_Peer *peer1;
 287
 288       /**
 289        * Handle for one of the disconnected peers.
 290        */
 291       struct GNUNET_TESTBED_Peer *peer2;
 292
 293     } peer_disconnect;
 294
 295     /**
 296      * Details about an operation finished event.
 297      */
 298     struct
 299     {
 300
 301       /**
 302        * Handle for the operation that was finished.
 303        */
 304       struct GNUNET_TESTBED_Operation *operation;
 305
 306       /**
 307        * Closure that was passed in when the event was
 308        * requested.
 309        */
 310       void *op_cls;
 311
 312       /**
 313        * Error message for the operation, NULL on success.
 314        */
 315       const char *emsg;
 316
 317       /**
 318        * Peer information type; captures which of the types
 319        * in the 'op_result' is actually in use.
 320        */
 321       enum GNUNET_TESTBED_PeerInformationType pit;
 322
 323       /**
 324        * Pointer to an operation-specific return value; NULL on error;
 325        * can be NULL for certain operations.  Valid until
 326        * 'GNUNET_TESTBED_operation_done' is called.
 327        */
 328       union
 329       {
 330         /**
 331          * No result (NULL pointer) or generic result
 332          * (whatever the GNUNET_TESTBED_ConnectAdapter returned).
 333          */
 334         void *generic;
 335
 336         /**
 337          * Identity of host running the peer.
 338          */
 339         struct GNUNET_TESTBED_Host *host;
 340
 341         /**
 342          * Identity of the peer.
 343          */
 344         const struct GNUNET_PeerIdentity *pid;
 345
 346         /**
 347          * Configuration of the peer.
 348          */
 349         const struct GNUNET_CONFIGURATION_Handle *cfg;
 350
 351       } op_result;
 352
 353     } operation_finished;
 354
 355
 356     /**
 357      * Details about an testbed run completed event.
 358      */
 359     struct
 360     {
 361
 362       /**
 363        * Error message for the operation, NULL on success.
 364        */
 365       const char *emsg;
 366
 367       /**
 368        * Array of peers now running (valid until
 369        * 'GNUNET_TESTBED_testbed_stop' is called).  Note that it is
 370        * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers
 371        * from this array.
 372        */
 373       struct GNUNET_TESTBED_Peer **peers;
 374
 375       /**
 376        * Size of the 'peers' array.
 377        */
 378       unsigned int num_peers;
 379
 380     } testbed_run_finished;
 381
 382   } details;
 383
 384 };
 385
 386
 387 /**
 388  * Signature of the event handler function called by the
 389  * respective event controller.
 390  *
 391  * @param cls closure
 392  * @param event information about the event
 393  */
 394 typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls,
 395                                                   const struct GNUNET_TESTBED_EventInformation *event);
 396
 397
 398 /**
 399  * Opaque Handle for Controller process
 400  */
 401 struct GNUNET_TESTBED_ControllerProc;
 402
 403
 404 /**
 405  * Starts a controller process at the host
 406  *
 407  * @param host the host where the controller has to be started; NULL for localhost
 408  * @return the controller process handle
 409  */
 410 struct GNUNET_TESTBED_ControllerProc *
 411 GNUNET_TESTBED_controller_start (struct GNUNET_TESTBED_Host *host);
 412
 413
 414 /**
 415  * Stop the controller process (also will terminate all peers and controllers
 416  * dependent on this controller).  This function blocks until the testbed has
 417  * been fully terminated (!).
 418  *
 419  * @param cproc the controller process handle
 420  */
 421 void
 422 GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc);
 423
 424
 425 /**
 426  * Connect to a controller process using the given configuration at the
 427  * given host.
 428  *
 429  * @param cfg configuration to use
 430  * @param host host to run the controller on; This should be the same host if
 431  *          the controller was previously started with
 432  *          GNUNET_TESTBED_controller_start; NULL for localhost
 433  * @param host host where this controller is being run;
 434  * @param event_mask bit mask with set of events to call 'cc' for;
 435  *                   or-ed values of "1LL" shifted by the
 436  *                   respective 'enum GNUNET_TESTBED_EventType'
 437  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...")
 438  * @param cc controller callback to invoke on events
 439  * @param cc_cls closure for cc
 440  * @return handle to the controller
 441  */
 442 struct GNUNET_TESTBED_Controller *
 443 GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 444                                    struct GNUNET_TESTBED_Host *host,
 445                                    uint64_t event_mask,
 446                                    GNUNET_TESTBED_ControllerCallback cc,
 447                                    void *cc_cls);
 448
 449
 450 /**
 451  * Configure shared services at a controller.  Using this function,
 452  * you can specify that certain services (such as "resolver")
 453  * should not be run for each peer but instead be shared
 454  * across N peers on the specified host.  This function
 455  * must be called before any peers are created at the host.
 456  *
 457  * @param controller controller to configure
 458  * @param service_name name of the service to share
 459  * @param num_peers number of peers that should share one instance
 460  *        of the specified service (1 for no sharing is the default),
 461  *        use 0 to disable the service
 462  */
 463 void
 464 GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller,
 465                                              const char *service_name,
 466                                              uint32_t num_peers);
 467
 468
 469 /**
 470  * Stop the given controller (also will terminate all peers and
 471  * controllers dependent on this controller).  This function
 472  * blocks until the testbed has been fully terminated (!).
 473  *
 474  * @param controller handle to controller to stop
 475  */
 476 void
 477 GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller);
 478
 479
 480 /**
 481  * Opaque handle for host registration
 482  */
 483 struct GNUNET_TESTBED_HostRegistrationHandle;
 484
 485
 486 /**
 487  * Callback which will be called to after a host registration succeeded or failed
 488  *
 489  * @param cls the closure
 490  * @param emsg the error message; NULL if host registration is successful
 491  */
 492 typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls,
 493                                                             const char *emsg);
 494
 495
 496 /**
 497  * Register a host with the controller
 498  *
 499  * @param controller the controller handle
 500  * @param host the host to register
 501  * @param cc the completion callback to call to inform the status of
 502  *          registration. After calling this callback the registration handle
 503  *          will be invalid. Cannot be NULL
 504  * @param cc_cls the closure for the cc
 505  * @return handle to the host registration which can be used to cancel the
 506  *           registration; NULL if another registration handle is present and
 507  *           is not cancelled
 508  */
 509 struct GNUNET_TESTBED_HostRegistrationHandle *
 510 GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller,
 511                               struct GNUNET_TESTBED_Host *host,
 512                               GNUNET_TESTBED_HostRegistrationCompletion cc,
 513                               void *cc_cls);
 514
 515
 516 /**
 517  * Cancel the pending registration. Note that the registration message will
 518  * already be queued to be sent to the service, cancellation has only the
 519  * effect that the registration completion callback for the registration is
 520  * never called and from our perspective the host is not registered until the
 521  * completion callback is called.
 522  *
 523  * @param handle the registration handle to cancel
 524  */
 525 void
 526 GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle
 527                                     *handle);
 528
 529
 530 /**
 531  * Create a link from slave controller to delegated controller. Whenever the
 532  * master controller is asked to start a peer at the delegated controller the
 533  * request will be routed towards slave controller (if a route exists). The
 534  * slave controller will then route it to the delegated controller. The
 535  * configuration of the slave controller is given and to be used to either
 536  * create the slave controller or to connect to an existing slave controller
 537  * process.  'is_subordinate' specifies if the given slave controller should be
 538  * started and managed by the master controller, or if the slave already has a
 539  * master and this is just a secondary master that is also allowed to use the
 540  * existing slave.
 541  *
 542  * @param master handle to the master controller who creates the association
 543  * @param delegated_host requests to which host should be delegated; cannot be NULL
 544  * @param slave_host which host is used to run the slave controller; use NULL to
 545  *          make the master controller connect to the delegated host
 546  * @param slave_cfg configuration to use for the slave controller
 547  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 548  *          be started by the master controller; GNUNET_NO if we are just
 549  *          allowed to use the slave via TCP/IP
 550  */
 551 void
 552 GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master,
 553                                 struct GNUNET_TESTBED_Host *delegated_host,
 554                                 struct GNUNET_TESTBED_Host *slave_host,
 555                                 const struct GNUNET_CONFIGURATION_Handle *slave_cfg,
 556                                 int is_subordinate);
 557
 558
 559 /**
 560  * Same as the GNUNET_TESTBED_controller_link, however expects configuration in
 561  * serialized and compressed
 562  *
 563  * @param master handle to the master controller who creates the association
 564  * @param delegated_host requests to which host should be delegated; cannot be NULL
 565  * @param slave_host which host is used to run the slave controller; use NULL to
 566  *          make the master controller connect to the delegated host
 567  * @param sxcfg serialized and compressed configuration
 568  * @param sxcfg_size the size scfg
 569  * @param scfg_size the size of uncompressed serialized configuration
 570  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 571  *          be started by the master controller; GNUNET_NO if we are just
 572  *          allowed to use the slave via TCP/IP
 573  */
 574 void
 575 GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master,
 576                                   struct GNUNET_TESTBED_Host *delegated_host,
 577                                   struct GNUNET_TESTBED_Host *slave_host,
 578                                   const char *sxcfg,
 579                                   size_t sxcfg_size,
 580                                   size_t scfg_size,
 581                                   int is_subordinate);
 582
 583
 584 /**
 585  * Create the given peer at the specified host using the given
 586  * controller.  If the given controller is not running on the target
 587  * host, it should find or create a controller at the target host and
 588  * delegate creating the peer.  Explicit delegation paths can be setup
 589  * using 'GNUNET_TESTBED_controller_link'.  If no explicit delegation
 590  * path exists, a direct link with a subordinate controller is setup
 591  * for the first delegated peer to a particular host; the subordinate
 592  * controller is then destroyed once the last peer that was delegated
 593  * to the remote host is stopped.
 594  *
 595  * Creating the peer only creates the handle to manipulate and further
 596  * configure the peer; use "GNUNET_TESTBED_peer_start" and
 597  * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's
 598  * processes.
 599  *
 600  * Note that the given configuration will be adjusted by the
 601  * controller to avoid port/path conflicts with other peers.
 602  * The "final" configuration can be obtained using
 603  * 'GNUNET_TESTBED_peer_get_information'.
 604  *
 605  * @param controller controller process to use
 606  * @param host host to run the peer on
 607  * @param cfg configuration to use for the peer
 608  * @return handle to the peer (actual startup will happen asynchronously)
 609  */
 610 struct GNUNET_TESTBED_Peer *
 611 GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller,
 612                             struct GNUNET_TESTBED_Host *host,
 613                             const struct GNUNET_CONFIGURATION_Handle *cfg);
 614
 615
 616 /**
 617  * Start the given peer.
 618  *
 619  * @param peer peer to start
 620  * @return handle to the operation
 621  */
 622 struct GNUNET_TESTBED_Operation *
 623 GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer);
 624
 625
 626 /**
 627  * Stop the given peer.  The handle remains valid (use
 628  * "GNUNET_TESTBED_peer_destroy" to fully clean up the
 629  * state of the peer).
 630  *
 631  * @param peer peer to stop
 632  * @return handle to the operation
 633  */
 634 struct GNUNET_TESTBED_Operation *
 635 GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer);
 636
 637
 638 /**
 639  * Request information about a peer.
 640  *
 641  * @param peer peer to request information about
 642  * @param pit desired information
 643  * @return handle to the operation
 644  */
 645 struct GNUNET_TESTBED_Operation *
 646 GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer,
 647                                      enum GNUNET_TESTBED_PeerInformationType pit);
 648
 649
 650 /**
 651  * Change peer configuration.  Must only be called while the
 652  * peer is stopped.  Ports and paths cannot be changed this
 653  * way.
 654  *
 655  * @param peer peer to change configuration for
 656  * @param cfg new configuration (differences to existing
 657  *            configuration only)
 658  * @return handle to the operation
 659  */
 660 struct GNUNET_TESTBED_Operation *
 661 GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer,
 662                                           const struct GNUNET_CONFIGURATION_Handle *cfg);
 663
 664
 665 /**
 666  * Destroy the given peer; the peer should have been
 667  * stopped first (if it was started).
 668  *
 669  * @param peer peer to stop
 670  * @return handle to the operation
 671  */
 672 struct GNUNET_TESTBED_Operation *
 673 GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer);
 674
 675
 676 /**
 677  * Options for peer connections.
 678  */
 679 enum GNUNET_TESTBED_ConnectOption
 680 {
 681   /**
 682    * No option (not valid as an argument).
 683    */
 684   GNUNET_TESTBED_CO_NONE = 0,
 685
 686   /**
 687    * Allow or disallow a connection between the specified peers.
 688    * Followed by GNUNET_NO (int) if a connection is disallowed
 689    * or GNUNET_YES if a connection is allowed.  Note that the
 690    * default (all connections allowed or disallowed) is
 691    * specified in the configuration of the controller.
 692    */
 693   GNUNET_TESTBED_CO_ALLOW = 1,
 694
 695   /**
 696    * FIXME: add (and implement) options to limit connection to
 697    * particular transports, force simulation of particular latencies
 698    * or message loss rates, or set bandwidth limitations.
 699    */
 700
 701 };
 702
 703
 704 /**
 705  * Manipulate the P2P underlay topology by configuring a link
 706  * between two peers.
 707  *
 708  * @param op_cls closure argument to give with the operation event
 709  * @param p1 first peer
 710  * @param p2 second peer
 711  * @param co option to change
 712  * @param ap option-specific values
 713  * @return handle to the operation, NULL if configuring the link at this
 714  *         time is not allowed
 715  */
 716 struct GNUNET_TESTBED_Operation *
 717 GNUNET_TESTBED_underlay_configure_link_va (void *op_cls,
 718                                            struct GNUNET_TESTBED_Peer *p1,
 719                                            struct GNUNET_TESTBED_Peer *p2,
 720                                            enum GNUNET_TESTBED_ConnectOption co,
 721                                            va_list ap);
 722
 723
 724 /**
 725  * Manipulate the P2P underlay topology by configuring a link
 726  * between two peers.
 727  *
 728  * @param op_cls closure argument to give with the operation event
 729  * @param p1 first peer
 730  * @param p2 second peer
 731  * @param co option to change
 732  * @param ... option-specific values
 733  * @return handle to the operation, NULL if configuring the link at this
 734  *         time is not allowed
 735  */
 736 struct GNUNET_TESTBED_Operation *
 737 GNUNET_TESTBED_underlay_configure_link (void *op_cls,
 738                                         struct GNUNET_TESTBED_Peer *p1,
 739                                         struct GNUNET_TESTBED_Peer *p2,
 740                                         enum GNUNET_TESTBED_ConnectOption co, ...);
 741
 742
 743
 744 /**
 745  * Topologies supported for testbeds.
 746  */
 747 enum GNUNET_TESTBED_TopologyOption
 748 {
 749   /**
 750    * A clique (everyone connected to everyone else).  No options.
 751    */
 752   GNUNET_TESTBED_TOPOLOGY_CLIQUE,
 753
 754   /**
 755    * Small-world network (2d torus plus random links).  Followed
 756    * by the number of random links to add (unsigned int).
 757    */
 758   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD,
 759
 760   /**
 761    * Small-world network (ring plus random links).  Followed
 762    * by the number of random links to add (unsigned int).
 763    */
 764   GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING,
 765
 766   /**
 767    * Ring topology.  No options.
 768    */
 769   GNUNET_TESTBED_TOPOLOGY_RING,
 770
 771   /**
 772    * 2-d torus.  No options.
 773    */
 774   GNUNET_TESTBED_TOPOLOGY_2D_TORUS,
 775
 776   /**
 777    * Random graph.  Followed by the link density, that is the
 778    * percentage of links present in relation to a clique
 779    * (float).
 780    */
 781   GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI,
 782
 783   /**
 784    * Certain percentage of peers are unable to communicate directly
 785    * replicating NAT conditions.  Followed by the fraction of
 786    * NAT'ed peers (float).
 787    */
 788   GNUNET_TESTBED_TOPOLOGY_INTERNAT,
 789
 790   /**
 791    * Scale free topology.   FIXME: options?
 792    */
 793   GNUNET_TESTBED_TOPOLOGY_SCALE_FREE,
 794
 795   /**
 796    * Straight line topology.  No options.
 797    */
 798   GNUNET_TESTBED_TOPOLOGY_LINE,
 799
 800   /**
 801    * All peers are disconnected.  No options.
 802    */
 803   GNUNET_TESTBED_TOPOLOGY_NONE,
 804
 805   /**
 806    * Read a topology from a given file.  Followed by the name of the file (const char *).
 807    */
 808   GNUNET_TESTBED_TOPOLOGY_FROM_FILE
 809 };
 810
 811
 812 /**
 813  * Configure overall network topology to have a particular shape.
 814  *
 815  * @param op_cls closure argument to give with the operation event
 816  * @param num_peers number of peers in 'peers'
 817  * @param peers array of 'num_peers' with the peers to configure
 818  * @param topo desired underlay topology to use
 819  * @param ap topology-specific options
 820  * @return handle to the operation, NULL if configuring the topology
 821  *         is not allowed at this time
 822  */
 823 struct GNUNET_TESTBED_Operation *
 824 GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls,
 825                                                unsigned int num_peers,
 826                                                struct GNUNET_TESTBED_Peer **peers,
 827                                                enum GNUNET_TESTBED_TopologyOption topo,
 828                                                va_list ap);
 829
 830
 831 /**
 832  * Configure overall network topology to have a particular shape.
 833  *
 834  * @param op_cls closure argument to give with the operation event
 835  * @param num_peers number of peers in 'peers'
 836  * @param peers array of 'num_peers' with the peers to configure
 837  * @param topo desired underlay topology to use
 838  * @param ... topology-specific options
 839  * @return handle to the operation, NULL if configuring the topology
 840  *         is not allowed at this time
 841  */
 842 struct GNUNET_TESTBED_Operation *
 843 GNUNET_TESTBED_underlay_configure_topology (void *op_cls,
 844                                             unsigned int num_peers,
 845                                             struct GNUNET_TESTBED_Peer **peers,
 846                                             enum GNUNET_TESTBED_TopologyOption topo,
 847                                             ...);
 848
 849
 850 /**
 851  * Both peers must have been started before calling this function.
 852  * This function then obtains a HELLO from 'p1', gives it to 'p2'
 853  * and asks 'p2' to connect to 'p1'.
 854  *
 855  * @param op_cls closure argument to give with the operation event
 856  * @param p1 first peer
 857  * @param p2 second peer
 858  * @return handle to the operation, NULL if connecting these two
 859  *         peers is fundamentally not possible at this time (peers
 860  *         not running or underlay disallows)
 861  */
 862 struct GNUNET_TESTBED_Operation *
 863 GNUNET_TESTBED_overlay_connect (void *op_cls,
 864                                 struct GNUNET_TESTBED_Peer *p1,
 865                                 struct GNUNET_TESTBED_Peer *p2);
 866
 867
 868 /**
 869  * All peers must have been started before calling this function.
 870  * This function then connects the given peers in the P2P overlay
 871  * using the given topology.
 872  *
 873  * @param op_cls closure argument to give with the operation event
 874  * @param num_peers number of peers in 'peers'
 875  * @param peers array of 'num_peers' with the peers to configure
 876  * @param topo desired underlay topology to use
 877  * @param va topology-specific options
 878  * @return handle to the operation, NULL if connecting these
 879  *         peers is fundamentally not possible at this time (peers
 880  *         not running or underlay disallows)
 881  */
 882 struct GNUNET_TESTBED_Operation *
 883 GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls,
 884                                               unsigned int num_peers,
 885                                               struct GNUNET_TESTBED_Peer *peers,
 886                                               enum GNUNET_TESTBED_TopologyOption topo,
 887                                               va_list va);
 888
 889
 890 /**
 891  * All peers must have been started before calling this function.
 892  * This function then connects the given peers in the P2P overlay
 893  * using the given topology.
 894  *
 895  * @param op_cls closure argument to give with the operation event
 896  * @param num_peers number of peers in 'peers'
 897  * @param peers array of 'num_peers' with the peers to configure
 898  * @param topo desired underlay topology to use
 899  * @param ... topology-specific options
 900  * @return handle to the operation, NULL if connecting these
 901  *         peers is fundamentally not possible at this time (peers
 902  *         not running or underlay disallows)
 903  */
 904 struct GNUNET_TESTBED_Operation *
 905 GNUNET_TESTBED_overlay_configure_topology (void *op_cls,
 906                                            unsigned int num_peers,
 907                                            struct GNUNET_TESTBED_Peer *peers,
 908                                            enum GNUNET_TESTBED_TopologyOption topo,
 909                                            ...);
 910
 911
 912 /**
 913  * Ask the testbed controller to write the current overlay topology to
 914  * a file.  Naturally, the file will only contain a snapshot as the
 915  * topology may evolve all the time.
 916  *
 917  * @param controller overlay controller to inspect
 918  * @param filename name of the file the topology should
 919  *        be written to.
 920  */
 921 void
 922 GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller,
 923                                                const char *filename);
 924
 925
 926 /**
 927  * Adapter function called to establish a connection to
 928  * a service.
 929  *
 930  * @param cls closure
 931  * @param cfg configuration of the peer to connect to
 932  * @return service handle to return in 'op_result', NULL on error
 933  */
 934 typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls,
 935                                                 const struct GNUNET_CONFIGURATION_Handle *cfg);
 936
 937
 938 /**
 939  * Adapter function called to destroy a connection to
 940  * a service.
 941  *
 942  * @param cls closure
 943  * @param op_result service handle returned from the connect adapter
 944  */
 945 typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls,
 946                                                  void *op_result);
 947
 948
 949 /**
 950  * Connect to a service offered by the given peer.  Will ensure that
 951  * the request is queued to not overwhelm our ability to create and
 952  * maintain connections with other systems.  The actual service
 953  * handle is then returned via the 'op_result' member in the event
 954  * callback.  The 'ca' callback is used to create the connection
 955  * when the time is right; the 'da' callback will be used to
 956  * destroy the connection (upon 'GNUNET_TESTBED_operation_done').
 957  * 'GNUNET_TESTBED_operation_cancel' can be used to abort this
 958  * operation until the event callback has been called.
 959  *
 960  * @param op_cls closure to pass in operation event
 961  * @param peer peer that runs the service
 962  * @param service_name name of the service to connect to
 963  * @param ca helper function to establish the connection
 964  * @param da helper function to close the connection
 965  * @param cada_cls closure for ca and da
 966  * @return handle for the operation
 967  */
 968 struct GNUNET_TESTBED_Operation *
 969 GNUNET_TESTBED_service_connect (void *op_cls,
 970                                 struct GNUNET_TESTBED_Peer *peer,
 971                                 const char *service_name,
 972                                 GNUNET_TESTBED_ConnectAdapter ca,
 973                                 GNUNET_TESTBED_DisconnectAdapter da,
 974                                 void *cada_cls);
 975
 976
 977 /**
 978  * Cancel a pending operation.  Releases all resources
 979  * of the operation and will ensure that no event
 980  * is generated for the operation.  Does NOT guarantee
 981  * that the operation will be fully undone (or that
 982  * nothing ever happened).
 983  *
 984  * @param operation operation to cancel
 985  */
 986 void
 987 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation);
 988
 989
 990 /**
 991  * Signal that the information from an operation has been fully
 992  * processed.  This function MUST be called for each event
 993  * of type 'operation_finished' to fully remove the operation
 994  * from the operation queue.  After calling this function, the
 995  * 'op_result' becomes invalid (!).
 996  *
 997  * @param operation operation to signal completion for
 998  */
 999 void
1000 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation);
1001
1002
1003 /**
1004  * Configure and run a testbed using the given
1005  * master controller on 'num_hosts' starting
1006  * 'num_peers' using the given peer configuration.
1007  *
1008  * @param controller master controller for the testbed
1009  *                   (must not be destroyed until after the
1010  *                    testbed is destroyed).
1011  * @param num_hosts number of hosts in 'hosts', 0 to only
1012  *        use 'localhost'
1013  * @param hosts list of hosts to use for the testbed
1014  * @param num_peers number of peers to start
1015  * @param peer_cfg peer configuration template to use
1016  * @param underlay_topology underlay topology to create
1017  * @param va topology-specific options
1018  * @return handle to the testbed
1019  */
1020 struct GNUNET_TESTBED_Testbed *
1021 GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller,
1022                           unsigned int num_hosts,
1023                           struct GNUNET_TESTBED_Host **hosts,
1024                           unsigned int num_peers,
1025                           const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1026                           enum GNUNET_TESTBED_TopologyOption underlay_topology,
1027                           va_list va);
1028
1029
1030 /**
1031  * Configure and run a testbed using the given
1032  * master controller on 'num_hosts' starting
1033  * 'num_peers' using the given peer configuration.
1034  *
1035  * @param controller master controller for the testbed
1036  *                   (must not be destroyed until after the
1037  *                    testbed is destroyed).
1038  * @param num_hosts number of hosts in 'hosts', 0 to only
1039  *        use 'localhost'
1040  * @param hosts list of hosts to use for the testbed
1041  * @param num_peers number of peers to start
1042  * @param peer_cfg peer configuration template to use
1043  * @param underlay_topology underlay topology to create
1044  * @param ... topology-specific options
1045  */
1046 struct GNUNET_TESTBED_Testbed *
1047 GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller,
1048                        unsigned int num_hosts,
1049                        struct GNUNET_TESTBED_Host **hosts,
1050                        unsigned int num_peers,
1051                        const struct GNUNET_CONFIGURATION_Handle *peer_cfg,
1052                        enum GNUNET_TESTBED_TopologyOption underlay_topology,
1053                        ...);
1054
1055
1056 /**
1057  * Destroy a testbed.  Stops all running peers and then
1058  * destroys all peers.  Does NOT destroy the master controller.
1059  *
1060  * @param testbed testbed to destroy
1061  */
1062 void
1063 GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed);
1064
1065
1066 /**
1067  * Convenience method for running a testbed with
1068  * a single call.  Underlay and overlay topology
1069  * are configured using the "UNDERLAY" and "OVERLAY"
1070  * options in the "[testbed]" section of the configuration\
1071  * (with possible options given in "UNDERLAY_XXX" and/or
1072  * "OVERLAY_XXX").
1073  *
1074  * The testbed is to be terminated using a call to
1075  * "GNUNET_SCHEDULER_shutdown".
1076  *
1077  * @param host_filename name of the file with the 'hosts', NULL
1078  *        to run everything on 'localhost'
1079  * @param cfg configuration to use (for testbed, controller and peers)
1080  * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg?
1081  * @param event_mask bit mask with set of events to call 'cc' for;
1082  *                   or-ed values of "1LL" shifted by the
1083  *                   respective 'enum GNUNET_TESTBED_EventType'
1084  *                   (i.e.  "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...")
1085  * @param cc controller callback to invoke on events
1086  * @param cc_cls closure for cc
1087  * @param master task to run once the testbed is ready
1088  * @param master_cls closure for 'task'.
1089  */
1090 void
1091 GNUNET_TESTBED_run (const char *host_filename,
1092                     const struct GNUNET_CONFIGURATION_Handle *cfg,
1093                     unsigned int num_peers,
1094                     uint64_t event_mask,
1095                     GNUNET_TESTBED_ControllerCallback cc,
1096                     void *cc_cls,
1097                     GNUNET_SCHEDULER_Task master,
1098                     void *master_cls);
1099
1100
1101 /**
1102  * Signature of a main function for a testcase.
1103  *
1104  * @param cls closure
1105  * @param num_peers number of peers in 'peers'
1106  * @param peers handle to peers run in the testbed
1107  */
1108 typedef void (*GNUNET_TESTBED_TestMaster)(void *cls,
1109                                           unsigned int num_peers,
1110                                           struct GNUNET_TESTBED_Peer **peers);
1111
1112
1113 /**
1114  * Convenience method for running a "simple" test on the local system
1115  * with a single call from 'main'.  Underlay and overlay topology are
1116  * configured using the "UNDERLAY" and "OVERLAY" options in the
1117  * "[testbed]" section of the configuration (with possible options
1118  * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX").
1119  *
1120  * The test is to be terminated using a call to
1121  * "GNUNET_SCHEDULER_shutdown".  If starting the test fails,
1122  * the program is stopped without 'master' ever being run.
1123  *
1124  * NOTE: this function should be called from 'main', NOT from
1125  * within a GNUNET_SCHEDULER-loop.  This function will initialze
1126  * the scheduler loop, the testbed and then pass control to
1127  * 'master'.
1128  *
1129  * @param testname name of the testcase (to configure logging, etc.)
1130  * @param cfg_filename configuration filename to use
1131  *              (for testbed, controller and peers)
1132  * @param num_peers number of peers to start
1133  * @param test_master task to run once the test is ready
1134  * @param test_master_cls closure for 'task'.
1135  */
1136 void
1137 GNUNET_TESTBED_test_run (const char *testname,
1138                          const char *cfg_filename,
1139                          unsigned int num_peers,
1140                          GNUNET_TESTBED_TestMaster test_master,
1141                          void *test_master_cls);
1142
1143
1144 #if 0                           /* keep Emacsens' auto-indent happy */
1145 {
1146 #endif
1147
1148
1149 #ifdef __cplusplus
1150 }
1151 #endif
1152
1153 #endif