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