src/testbed/testbed.h

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