src/testbed/testbed.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--2013 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 testbed/testbed.h
  23  * @brief IPC messages between testing API and service ("controller")
  24  * @author Christian Grothoff
  25  */
  26
  27 #ifndef TESTBED_H
  28 #define TESTBED_H
  29
  30 #include "gnunet_util_lib.h"
  31
  32 GNUNET_NETWORK_STRUCT_BEGIN
  33 /**
  34  * Initial message from a client to a testing control service.
  35  */
  36     struct GNUNET_TESTBED_InitMessage
  37 {
  38
  39   /**
  40    * Type is GNUNET_MESSAGE_TYPE_TESTBED_INIT
  41    */
  42   struct GNUNET_MessageHeader header;
  43
  44   /**
  45    * Host ID that the controller is either given (if this is the
  46    * dominating client) or assumed to have (for peer-connections
  47    * between controllers).  A controller must check that all
  48    * connections make consistent claims...
  49    */
  50   uint32_t host_id GNUNET_PACKED;
  51
  52   /**
  53    * Event mask that specifies which events this client
  54    * is interested in.  In NBO.
  55    */
  56   uint64_t event_mask GNUNET_PACKED;
  57
  58   /* Followed by 0-terminated hostname of the controller */
  59 };
  60
  61
  62 /**
  63  * Notify the service about a host that we intend to use.
  64  */
  65 struct GNUNET_TESTBED_AddHostMessage
  66 {
  67
  68   /**
  69    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST
  70    */
  71   struct GNUNET_MessageHeader header;
  72
  73   /**
  74    * Unique ID for the host (in NBO).
  75    */
  76   uint32_t host_id GNUNET_PACKED;
  77
  78   /**
  79    * SSH port to use, 0 for default (in NBO).
  80    */
  81   uint16_t ssh_port GNUNET_PACKED;
  82
  83   /**
  84    * Number of bytes in the user name that follows;
  85    * 0 to use no user name; otherwise 'strlen (username)',
  86    * excluding 0-termination!
  87    */
  88   uint16_t username_length GNUNET_PACKED;
  89
  90   /**
  91    * Number of bytes in the host name (excluding 0-termination) that follows the
  92    * user name; cannot be 0
  93    */
  94   uint16_t hostname_length GNUNET_PACKED;
  95
  96   /**
  97    * The length of the uncompressed configuration
  98    */
  99   uint16_t config_size GNUNET_PACKED;
 100
 101   /* followed by non 0-terminated user name */
 102
 103   /* followed by non 0-terminated host name */
 104
 105   /* followed by gzip compressed configuration to start or connect to a
 106      controller on this host.  While starting the controller this configration
 107      is used as a template */
 108
 109 };
 110
 111
 112 /**
 113  * Confirmation from the service that adding a host
 114  * worked (or failed).
 115  * FIXME: Where is this required?
 116  */
 117 struct GNUNET_TESTBED_HostConfirmedMessage
 118 {
 119
 120   /**
 121    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST_SUCCESS
 122    */
 123   struct GNUNET_MessageHeader header;
 124
 125   /**
 126    * Unique ID for the host (in NBO).
 127    */
 128   uint32_t host_id GNUNET_PACKED;
 129
 130   /* followed by the 0-terminated error message (on failure)
 131    * (typical errors include host-id already in use) */
 132
 133 };
 134
 135
 136 /**
 137  * Message to testing service: configure service sharing
 138  * at a host.
 139  */
 140 struct GNUNET_TESTBED_ConfigureSharedServiceMessage
 141 {
 142
 143   /**
 144    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHARE_SERVICE
 145    */
 146   struct GNUNET_MessageHeader header;
 147
 148   /**
 149    * Host that is being configured.
 150    */
 151   uint32_t host_id GNUNET_PACKED;
 152
 153   /**
 154    * Number of peers that should share a service instance;
 155    * 1 for no sharing, 0 to forcefully disable the service.
 156    */
 157   uint32_t num_peers GNUNET_PACKED;
 158
 159   /* followed by 0-terminated name of the service */
 160
 161 };
 162
 163
 164 /**
 165  * Client notifies controller that it should delegate
 166  * requests for a particular client to a particular
 167  * sub-controller.
 168  */
 169 struct GNUNET_TESTBED_ControllerLinkRequest
 170 {
 171
 172   /**
 173    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS
 174    */
 175   struct GNUNET_MessageHeader header;
 176
 177   /**
 178    * For which host should requests be delegated? NBO.
 179    */
 180   uint32_t delegated_host_id GNUNET_PACKED;
 181
 182   /**
 183    * The id of the operation which created this message
 184    */
 185   uint64_t operation_id GNUNET_PACKED;
 186
 187   /**
 188    * Which host is responsible for managing the delegation? NBO
 189    */
 190   uint32_t slave_host_id GNUNET_PACKED;
 191
 192   /**
 193    * Set to 1 if the receiving controller is the master controller for
 194    * the slave host (and thus responsible for starting it?). 0 if not
 195    */
 196   uint8_t is_subordinate;
 197
 198 };
 199
 200
 201 /**
 202  * Response message for ControllerLinkRequest message
 203  */
 204 struct GNUNET_TESTBED_ControllerLinkResponse
 205 {
 206
 207   /**
 208    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS_RESULT
 209    */
 210   struct GNUNET_MessageHeader header;
 211
 212   /**
 213    * The size of the compressed configuration. Can be ZERO if the controller is
 214    * not started (depends on the ControllerLinkRequest). NBO.
 215    */
 216   uint16_t config_size GNUNET_PACKED;
 217
 218   /**
 219    * Set to GNUNET_YES to signify SUCCESS; GNUNET_NO to signify failure
 220    */
 221   uint16_t success GNUNET_PACKED;
 222
 223   /**
 224    * The id of the operation which created this message. NBO
 225    */
 226   uint64_t operation_id GNUNET_PACKED;
 227
 228   /* If controller linking is successful and configuration is present, then here
 229    * comes the serialized gzip configuration with which the controller is
 230    * running at the delegate host */
 231
 232   /* In case of failure, here comes the error message (without \0 termination)*/
 233
 234 };
 235
 236
 237 /**
 238  * Message sent from client to testing service to
 239  * create (configure, but not start) a peer.
 240  */
 241 struct GNUNET_TESTBED_PeerCreateMessage
 242 {
 243
 244   /**
 245    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER
 246    */
 247   struct GNUNET_MessageHeader header;
 248
 249   /**
 250    * Unique operation id
 251    */
 252   uint64_t operation_id GNUNET_PACKED;
 253
 254   /**
 255    * On which host should the peer be started?
 256    */
 257   uint32_t host_id GNUNET_PACKED;
 258
 259   /**
 260    * Unique ID for the peer.
 261    */
 262   uint32_t peer_id GNUNET_PACKED;
 263
 264   /**
 265    * Size of the uncompressed configuration
 266    */
 267   uint32_t config_size GNUNET_PACKED;
 268
 269   /* followed by serialized peer configuration;
 270    * gzip'ed configuration file in INI format */
 271
 272 };
 273
 274
 275 /**
 276  * Message sent from client to testing service to
 277  * reconfigure a (stopped) a peer.
 278  */
 279 struct GNUNET_TESTBED_PeerReconfigureMessage
 280 {
 281
 282   /**
 283    * Type is GNUNET_MESSAGE_TYPDE_TESTBED_RECONFIGURE_PEER
 284    */
 285   struct GNUNET_MessageHeader header;
 286
 287   /**
 288    * Unique ID for the peer.
 289    */
 290   uint32_t peer_id GNUNET_PACKED;
 291
 292   /**
 293    * Operation ID that is used to identify this operation.
 294    */
 295   uint64_t operation_id GNUNET_PACKED;
 296
 297   /* followed by serialized peer configuration;
 298    * gzip'ed configuration file in INI format */
 299
 300 };
 301
 302
 303 /**
 304  * Message sent from client to testing service to
 305  * start a peer.
 306  */
 307 struct GNUNET_TESTBED_PeerStartMessage
 308 {
 309
 310   /**
 311    * Type is GNUNET_MESSAGE_TYPE_TESTBED_START_PEER
 312    */
 313   struct GNUNET_MessageHeader header;
 314
 315   /**
 316    * Unique ID for the peer.
 317    */
 318   uint32_t peer_id GNUNET_PACKED;
 319
 320   /**
 321    * Operation ID that is used to identify this operation.
 322    */
 323   uint64_t operation_id GNUNET_PACKED;
 324
 325 };
 326
 327
 328 /**
 329  * Message sent from client to testing service to
 330  * stop a peer.
 331  */
 332 struct GNUNET_TESTBED_PeerStopMessage
 333 {
 334
 335   /**
 336    * Type is GNUNET_MESSAGE_TYPE_TESTBED_STOP_PEER
 337    */
 338   struct GNUNET_MessageHeader header;
 339
 340   /**
 341    * Unique ID for the peer.
 342    */
 343   uint32_t peer_id GNUNET_PACKED;
 344
 345   /**
 346    * Operation ID that is used to identify this operation.
 347    */
 348   uint64_t operation_id GNUNET_PACKED;
 349
 350 };
 351
 352
 353 /**
 354  * Message sent from client to testing service to
 355  * destroy a (stopped) peer.
 356  */
 357 struct GNUNET_TESTBED_PeerDestroyMessage
 358 {
 359
 360   /**
 361    * Type is GNUNET_MESSAGE_TYPE_TESTBED_DESTROY_PEER
 362    */
 363   struct GNUNET_MessageHeader header;
 364
 365   /**
 366    * Unique ID for the peer.
 367    */
 368   uint32_t peer_id GNUNET_PACKED;
 369
 370   /**
 371    * Operation ID that is used to identify this operation.
 372    */
 373   uint64_t operation_id GNUNET_PACKED;
 374
 375 };
 376
 377
 378 /**
 379  * Message sent from client to testing service to
 380  * (re)configure a "physical" link between two peers.
 381  */
 382 struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage
 383 {
 384
 385   /**
 386    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CONFIGURE_UNDERLAY_LINK
 387    */
 388   struct GNUNET_MessageHeader header;
 389
 390   /**
 391    * 'enum GNUNET_TESTBED_ConnectOption' of the option to change
 392    */
 393   int32_t connect_option GNUNET_PACKED;
 394
 395   /**
 396    * Unique ID for the first peer.
 397    */
 398   uint32_t peer1 GNUNET_PACKED;
 399
 400   /**
 401    * Unique ID for the second peer.
 402    */
 403   uint32_t peer2 GNUNET_PACKED;
 404
 405   /**
 406    * Operation ID that is used to identify this operation.
 407    */
 408   uint64_t operation_id GNUNET_PACKED;
 409
 410   /* followed by option-dependent variable-size values */
 411
 412 };
 413
 414
 415 /**
 416  * Message sent from client to testing service to
 417  * connect two peers.
 418  */
 419 struct GNUNET_TESTBED_OverlayConnectMessage
 420 {
 421
 422   /**
 423    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OVERLAY_CONNECT
 424    */
 425   struct GNUNET_MessageHeader header;
 426
 427   /**
 428    * Unique ID for the first peer.
 429    */
 430   uint32_t peer1 GNUNET_PACKED;
 431
 432   /**
 433    * Operation ID that is used to identify this operation.
 434    */
 435   uint64_t operation_id GNUNET_PACKED;
 436
 437   /**
 438    * Unique ID for the second peer.
 439    */
 440   uint32_t peer2 GNUNET_PACKED;
 441
 442   /**
 443    * The ID of the host which runs peer2
 444    */
 445   uint32_t peer2_host_id GNUNET_PACKED;
 446
 447 };
 448
 449
 450 /**
 451  * Message sent from host controller of a peer(A) to the host controller of
 452  * another peer(B) to request B to connect to A
 453  */
 454 struct GNUNET_TESTBED_RemoteOverlayConnectMessage
 455 {
 456   /**
 457    * Type is GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT
 458    */
 459   struct GNUNET_MessageHeader header;
 460
 461   /**
 462    * The Unique ID of B
 463    */
 464   uint32_t peer GNUNET_PACKED;
 465
 466   /**
 467    * The Operation ID that is used to identify this operation
 468    */
 469   uint64_t operation_id GNUNET_PACKED;
 470
 471   /**
 472    * Identity of A
 473    */
 474   struct GNUNET_PeerIdentity peer_identity;
 475
 476   /**
 477    * To be followed by the HELLO message of A
 478    */
 479   struct GNUNET_MessageHeader hello[0];
 480
 481 };
 482
 483
 484 /**
 485  * Event notification from a controller to a client.
 486  */
 487 struct GNUNET_TESTBED_PeerEventMessage
 488 {
 489
 490   /**
 491    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_EVENT
 492    */
 493   struct GNUNET_MessageHeader header;
 494
 495   /**
 496    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 497    * either GNUNET_TESTBED_ET_PEER_START or GNUNET_TESTBED_ET_PEER_STOP.
 498    */
 499   int32_t event_type GNUNET_PACKED;
 500
 501   /**
 502    * Host where the peer is running.
 503    */
 504   uint32_t host_id GNUNET_PACKED;
 505
 506   /**
 507    * Peer that was started or stopped.
 508    */
 509   uint32_t peer_id GNUNET_PACKED;
 510
 511   /**
 512    * Operation ID that is used to identify this operation.
 513    */
 514   uint64_t operation_id GNUNET_PACKED;
 515
 516 };
 517
 518
 519 /**
 520  * Event notification from a controller to a client.
 521  */
 522 struct GNUNET_TESTBED_ConnectionEventMessage
 523 {
 524
 525   /**
 526    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONNECT_EVENT
 527    */
 528   struct GNUNET_MessageHeader header;
 529
 530   /**
 531    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 532    * either GNUNET_TESTBED_ET_CONNECT or GNUNET_TESTBED_ET_DISCONNECT.
 533    */
 534   int32_t event_type GNUNET_PACKED;
 535
 536   /**
 537    * First peer.
 538    */
 539   uint32_t peer1 GNUNET_PACKED;
 540
 541   /**
 542    * Second peer.
 543    */
 544   uint32_t peer2 GNUNET_PACKED;
 545
 546   /**
 547    * Operation ID that is used to identify this operation.
 548    */
 549   uint64_t operation_id GNUNET_PACKED;
 550
 551 };
 552
 553
 554 /**
 555  * Event notification from a controller to a client.
 556  */
 557 struct GNUNET_TESTBED_OperationFailureEventMessage
 558 {
 559
 560   /**
 561    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OPERATION_FAIL_EVENT
 562    */
 563   struct GNUNET_MessageHeader header;
 564
 565   /**
 566    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 567    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 568    */
 569   int32_t event_type GNUNET_PACKED;
 570
 571   /**
 572    * Operation ID of the operation that created this event.
 573    */
 574   uint64_t operation_id GNUNET_PACKED;
 575
 576   /* followed by 0-terminated error message */
 577
 578 };
 579
 580
 581 /**
 582  * Event notification from a controller to a client.
 583  */
 584 struct GNUNET_TESTBED_PeerCreateSuccessEventMessage
 585 {
 586
 587   /**
 588    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER_SUCCESS
 589    */
 590   struct GNUNET_MessageHeader header;
 591
 592   /**
 593    * Peer identity of the peer that was created.
 594    */
 595   uint32_t peer_id GNUNET_PACKED;
 596
 597   /**
 598    * Operation ID of the operation that created this event.
 599    */
 600   uint64_t operation_id GNUNET_PACKED;
 601
 602 };
 603
 604
 605 /**
 606  * Event notification from a controller to a client for
 607  * a generic operational success where the operation does
 608  * not return any data.
 609  */
 610 struct GNUNET_TESTBED_GenericOperationSuccessEventMessage
 611 {
 612
 613   /**
 614    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GENERIC_OPERATION_SUCCESS
 615    */
 616   struct GNUNET_MessageHeader header;
 617
 618   /**
 619    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 620    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 621    */
 622   int32_t event_type GNUNET_PACKED;
 623
 624   /**
 625    * Operation ID of the operation that created this event.
 626    */
 627   uint64_t operation_id GNUNET_PACKED;
 628
 629 };
 630
 631
 632 /**
 633  * Message sent from client to testing service to
 634  * obtain the configuration of a peer.
 635  */
 636 struct GNUNET_TESTBED_PeerGetConfigurationMessage
 637 {
 638
 639   /**
 640    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_PEER_CONFIGURATION
 641    */
 642   struct GNUNET_MessageHeader header;
 643
 644   /**
 645    * Unique ID for the peer.
 646    */
 647   uint32_t peer_id GNUNET_PACKED;
 648
 649   /**
 650    * Operation ID that is used to identify this operation.
 651    */
 652   uint64_t operation_id GNUNET_PACKED;
 653
 654 };
 655
 656
 657 /**
 658  * Peer configuration and identity reply from controller to a client.
 659  */
 660 struct GNUNET_TESTBED_PeerConfigurationInformationMessage
 661 {
 662
 663   /**
 664    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONFIGURATION
 665    */
 666   struct GNUNET_MessageHeader header;
 667
 668   /**
 669    * The id of the peer relevant to this information
 670    */
 671   uint32_t peer_id GNUNET_PACKED;
 672
 673   /**
 674    * Operation ID of the operation that created this event.
 675    */
 676   uint64_t operation_id GNUNET_PACKED;
 677
 678   /**
 679    * Identity of the peer.
 680    */
 681   struct GNUNET_PeerIdentity peer_identity;
 682
 683   /**
 684    * The size of configuration when uncompressed
 685    */
 686   uint16_t config_size GNUNET_PACKED;
 687
 688   /* followed by gzip-compressed configuration of the peer */
 689
 690 };
 691
 692
 693 /**
 694  * Message to request configuration of a slave controller
 695  */
 696 struct GNUNET_TESTBED_SlaveGetConfigurationMessage
 697 {
 698   /**
 699    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIGURATION
 700    */
 701   struct GNUNET_MessageHeader header;
 702
 703   /**
 704    * The id of the slave host
 705    */
 706   uint32_t slave_id GNUNET_PACKED;
 707
 708   /**
 709    * Operation ID
 710    */
 711   uint64_t operation_id GNUNET_PACKED;
 712
 713 };
 714
 715
 716 /**
 717  * Reply to GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIG message
 718  */
 719 struct GNUNET_TESTBED_SlaveConfiguration
 720 {
 721   /**
 722    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SLAVE_CONFIGURATION
 723    */
 724   struct GNUNET_MessageHeader header;
 725
 726   /**
 727    * The id of the host where the slave is running
 728    */
 729   uint32_t slave_id GNUNET_PACKED;
 730
 731   /**
 732    * Operation ID
 733    */
 734   uint64_t operation_id GNUNET_PACKED;
 735
 736   /**
 737    * The size of the configuration when uncompressed
 738    */
 739   uint16_t config_size GNUNET_PACKED;
 740
 741   /* followed by gzip-compressed configuration of the peer */
 742
 743 };
 744
 745
 746 /**
 747  * Shutdown peers message
 748  */
 749 struct GNUNET_TESTBED_ShutdownPeersMessage
 750 {
 751   /**
 752    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
 753    */
 754   struct GNUNET_MessageHeader header;
 755
 756   /**
 757    * Operation ID
 758    */
 759   uint64_t operation_id GNUNET_PACKED;
 760 };
 761
 762
 763 /**
 764  * Message to start/stop services of a peer
 765  */
 766 struct GNUNET_TESTBED_ManagePeerServiceMessage
 767 {
 768   /**
 769    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
 770    */
 771   struct GNUNET_MessageHeader header;
 772
 773   /**
 774    * Unique ID of the peer whose service has to be managed.
 775    */
 776   uint32_t peer_id GNUNET_PACKED;
 777
 778   /**
 779    * Operation ID
 780    */
 781   uint64_t operation_id GNUNET_PACKED;
 782
 783   /**
 784    * set this to 1 to start the service; 0 to stop the service
 785    */
 786   uint8_t start;
 787
 788   /**
 789    * The NULL-terminated name of the service to start/stop follows here
 790    */
 791 };
 792
 793
 794 GNUNET_NETWORK_STRUCT_END
 795 #endif
 796 /* end of testbed.h */