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    * The size of the uncompressed configuration
 194    */
 195   uint16_t config_size GNUNET_PACKED;
 196
 197   /**
 198    * Set to 1 if the receiving controller is the master controller for
 199    * the slave host (and thus responsible for starting it?). 0 if not
 200    */
 201   uint8_t is_subordinate;
 202
 203   /* followed by serialized slave configuration;
 204    * gzip'ed configuration file in INI format */
 205
 206 };
 207
 208
 209 /**
 210  * Response message for ControllerLinkRequest message
 211  */
 212 struct GNUNET_TESTBED_ControllerLinkResponse
 213 {
 214
 215   /**
 216    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS_RESULT
 217    */
 218   struct GNUNET_MessageHeader header;
 219
 220   /**
 221    * The size of the compressed configuration. Can be ZERO if the controller is
 222    * not started (depends on the ControllerLinkRequest). NBO.
 223    */
 224   uint16_t config_size GNUNET_PACKED;
 225
 226   /**
 227    * Set to GNUNET_YES to signify SUCCESS; GNUNET_NO to signify failure
 228    */
 229   uint16_t success GNUNET_PACKED;
 230
 231   /**
 232    * The id of the operation which created this message. NBO
 233    */
 234   uint64_t operation_id GNUNET_PACKED;
 235
 236   /* If controller linking is successful and configuration is present, then here
 237    * comes the serialized gzip configuration with which the controller is
 238    * running at the delegate host */
 239
 240   /* In case of failure, here comes the error message (without \0 termination)*/
 241
 242 };
 243
 244
 245 /**
 246  * Message sent from client to testing service to
 247  * create (configure, but not start) a peer.
 248  */
 249 struct GNUNET_TESTBED_PeerCreateMessage
 250 {
 251
 252   /**
 253    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER
 254    */
 255   struct GNUNET_MessageHeader header;
 256
 257   /**
 258    * Unique operation id
 259    */
 260   uint64_t operation_id GNUNET_PACKED;
 261
 262   /**
 263    * On which host should the peer be started?
 264    */
 265   uint32_t host_id GNUNET_PACKED;
 266
 267   /**
 268    * Unique ID for the peer.
 269    */
 270   uint32_t peer_id GNUNET_PACKED;
 271
 272   /**
 273    * Size of the uncompressed configuration
 274    */
 275   uint32_t config_size GNUNET_PACKED;
 276
 277   /* followed by serialized peer configuration;
 278    * gzip'ed configuration file in INI format */
 279
 280 };
 281
 282
 283 /**
 284  * Message sent from client to testing service to
 285  * reconfigure a (stopped) a peer.
 286  */
 287 struct GNUNET_TESTBED_PeerReconfigureMessage
 288 {
 289
 290   /**
 291    * Type is GNUNET_MESSAGE_TYPDE_TESTBED_RECONFIGURE_PEER
 292    */
 293   struct GNUNET_MessageHeader header;
 294
 295   /**
 296    * Unique ID for the peer.
 297    */
 298   uint32_t peer_id GNUNET_PACKED;
 299
 300   /**
 301    * Operation ID that is used to identify this operation.
 302    */
 303   uint64_t operation_id GNUNET_PACKED;
 304
 305   /* followed by serialized peer configuration;
 306    * gzip'ed configuration file in INI format */
 307
 308 };
 309
 310
 311 /**
 312  * Message sent from client to testing service to
 313  * start a peer.
 314  */
 315 struct GNUNET_TESTBED_PeerStartMessage
 316 {
 317
 318   /**
 319    * Type is GNUNET_MESSAGE_TYPE_TESTBED_START_PEER
 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  * stop a peer.
 339  */
 340 struct GNUNET_TESTBED_PeerStopMessage
 341 {
 342
 343   /**
 344    * Type is GNUNET_MESSAGE_TYPE_TESTBED_STOP_PEER
 345    */
 346   struct GNUNET_MessageHeader header;
 347
 348   /**
 349    * Unique ID for the peer.
 350    */
 351   uint32_t peer_id GNUNET_PACKED;
 352
 353   /**
 354    * Operation ID that is used to identify this operation.
 355    */
 356   uint64_t operation_id GNUNET_PACKED;
 357
 358 };
 359
 360
 361 /**
 362  * Message sent from client to testing service to
 363  * destroy a (stopped) peer.
 364  */
 365 struct GNUNET_TESTBED_PeerDestroyMessage
 366 {
 367
 368   /**
 369    * Type is GNUNET_MESSAGE_TYPE_TESTBED_DESTROY_PEER
 370    */
 371   struct GNUNET_MessageHeader header;
 372
 373   /**
 374    * Unique ID for the peer.
 375    */
 376   uint32_t peer_id GNUNET_PACKED;
 377
 378   /**
 379    * Operation ID that is used to identify this operation.
 380    */
 381   uint64_t operation_id GNUNET_PACKED;
 382
 383 };
 384
 385
 386 /**
 387  * Message sent from client to testing service to
 388  * (re)configure a "physical" link between two peers.
 389  */
 390 struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage
 391 {
 392
 393   /**
 394    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CONFIGURE_UNDERLAY_LINK
 395    */
 396   struct GNUNET_MessageHeader header;
 397
 398   /**
 399    * 'enum GNUNET_TESTBED_ConnectOption' of the option to change
 400    */
 401   int32_t connect_option GNUNET_PACKED;
 402
 403   /**
 404    * Unique ID for the first peer.
 405    */
 406   uint32_t peer1 GNUNET_PACKED;
 407
 408   /**
 409    * Unique ID for the second peer.
 410    */
 411   uint32_t peer2 GNUNET_PACKED;
 412
 413   /**
 414    * Operation ID that is used to identify this operation.
 415    */
 416   uint64_t operation_id GNUNET_PACKED;
 417
 418   /* followed by option-dependent variable-size values */
 419
 420 };
 421
 422
 423 /**
 424  * Message sent from client to testing service to
 425  * connect two peers.
 426  */
 427 struct GNUNET_TESTBED_OverlayConnectMessage
 428 {
 429
 430   /**
 431    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OVERLAY_CONNECT
 432    */
 433   struct GNUNET_MessageHeader header;
 434
 435   /**
 436    * Unique ID for the first peer.
 437    */
 438   uint32_t peer1 GNUNET_PACKED;
 439
 440   /**
 441    * Operation ID that is used to identify this operation.
 442    */
 443   uint64_t operation_id GNUNET_PACKED;
 444
 445   /**
 446    * Unique ID for the second peer.
 447    */
 448   uint32_t peer2 GNUNET_PACKED;
 449
 450   /**
 451    * The ID of the host which runs peer2
 452    */
 453   uint32_t peer2_host_id GNUNET_PACKED;
 454
 455 };
 456
 457
 458 /**
 459  * Message sent from host controller of a peer(A) to the host controller of
 460  * another peer(B) to request B to connect to A
 461  */
 462 struct GNUNET_TESTBED_RemoteOverlayConnectMessage
 463 {
 464   /**
 465    * Type is GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT
 466    */
 467   struct GNUNET_MessageHeader header;
 468
 469   /**
 470    * The Unique ID of B
 471    */
 472   uint32_t peer GNUNET_PACKED;
 473
 474   /**
 475    * The Operation ID that is used to identify this operation
 476    */
 477   uint64_t operation_id GNUNET_PACKED;
 478
 479   /**
 480    * Identity of A
 481    */
 482   struct GNUNET_PeerIdentity peer_identity;
 483
 484   /**
 485    * To be followed by the HELLO message of A
 486    */
 487   struct GNUNET_MessageHeader hello[0];
 488
 489 };
 490
 491
 492 /**
 493  * Event notification from a controller to a client.
 494  */
 495 struct GNUNET_TESTBED_PeerEventMessage
 496 {
 497
 498   /**
 499    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_EVENT
 500    */
 501   struct GNUNET_MessageHeader header;
 502
 503   /**
 504    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 505    * either GNUNET_TESTBED_ET_PEER_START or GNUNET_TESTBED_ET_PEER_STOP.
 506    */
 507   int32_t event_type GNUNET_PACKED;
 508
 509   /**
 510    * Host where the peer is running.
 511    */
 512   uint32_t host_id GNUNET_PACKED;
 513
 514   /**
 515    * Peer that was started or stopped.
 516    */
 517   uint32_t peer_id GNUNET_PACKED;
 518
 519   /**
 520    * Operation ID that is used to identify this operation.
 521    */
 522   uint64_t operation_id GNUNET_PACKED;
 523
 524 };
 525
 526
 527 /**
 528  * Event notification from a controller to a client.
 529  */
 530 struct GNUNET_TESTBED_ConnectionEventMessage
 531 {
 532
 533   /**
 534    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONNECT_EVENT
 535    */
 536   struct GNUNET_MessageHeader header;
 537
 538   /**
 539    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 540    * either GNUNET_TESTBED_ET_CONNECT or GNUNET_TESTBED_ET_DISCONNECT.
 541    */
 542   int32_t event_type GNUNET_PACKED;
 543
 544   /**
 545    * First peer.
 546    */
 547   uint32_t peer1 GNUNET_PACKED;
 548
 549   /**
 550    * Second peer.
 551    */
 552   uint32_t peer2 GNUNET_PACKED;
 553
 554   /**
 555    * Operation ID that is used to identify this operation.
 556    */
 557   uint64_t operation_id GNUNET_PACKED;
 558
 559 };
 560
 561
 562 /**
 563  * Event notification from a controller to a client.
 564  */
 565 struct GNUNET_TESTBED_OperationFailureEventMessage
 566 {
 567
 568   /**
 569    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OPERATION_FAIL_EVENT
 570    */
 571   struct GNUNET_MessageHeader header;
 572
 573   /**
 574    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 575    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 576    */
 577   int32_t event_type GNUNET_PACKED;
 578
 579   /**
 580    * Operation ID of the operation that created this event.
 581    */
 582   uint64_t operation_id GNUNET_PACKED;
 583
 584   /* followed by 0-terminated error message */
 585
 586 };
 587
 588
 589 /**
 590  * Event notification from a controller to a client.
 591  */
 592 struct GNUNET_TESTBED_PeerCreateSuccessEventMessage
 593 {
 594
 595   /**
 596    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER_SUCCESS
 597    */
 598   struct GNUNET_MessageHeader header;
 599
 600   /**
 601    * Peer identity of the peer that was created.
 602    */
 603   uint32_t peer_id GNUNET_PACKED;
 604
 605   /**
 606    * Operation ID of the operation that created this event.
 607    */
 608   uint64_t operation_id GNUNET_PACKED;
 609
 610 };
 611
 612
 613 /**
 614  * Event notification from a controller to a client for
 615  * a generic operational success where the operation does
 616  * not return any data.
 617  */
 618 struct GNUNET_TESTBED_GenericOperationSuccessEventMessage
 619 {
 620
 621   /**
 622    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GENERIC_OPERATION_SUCCESS
 623    */
 624   struct GNUNET_MessageHeader header;
 625
 626   /**
 627    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 628    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 629    */
 630   int32_t event_type GNUNET_PACKED;
 631
 632   /**
 633    * Operation ID of the operation that created this event.
 634    */
 635   uint64_t operation_id GNUNET_PACKED;
 636
 637 };
 638
 639
 640 /**
 641  * Message sent from client to testing service to
 642  * obtain the configuration of a peer.
 643  */
 644 struct GNUNET_TESTBED_PeerGetConfigurationMessage
 645 {
 646
 647   /**
 648    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_PEER_CONFIGURATION
 649    */
 650   struct GNUNET_MessageHeader header;
 651
 652   /**
 653    * Unique ID for the peer.
 654    */
 655   uint32_t peer_id GNUNET_PACKED;
 656
 657   /**
 658    * Operation ID that is used to identify this operation.
 659    */
 660   uint64_t operation_id GNUNET_PACKED;
 661
 662 };
 663
 664
 665 /**
 666  * Peer configuration and identity reply from controller to a client.
 667  */
 668 struct GNUNET_TESTBED_PeerConfigurationInformationMessage
 669 {
 670
 671   /**
 672    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONFIGURATION
 673    */
 674   struct GNUNET_MessageHeader header;
 675
 676   /**
 677    * The id of the peer relevant to this information
 678    */
 679   uint32_t peer_id GNUNET_PACKED;
 680
 681   /**
 682    * Operation ID of the operation that created this event.
 683    */
 684   uint64_t operation_id GNUNET_PACKED;
 685
 686   /**
 687    * Identity of the peer.
 688    */
 689   struct GNUNET_PeerIdentity peer_identity;
 690
 691   /**
 692    * The size of configuration when uncompressed
 693    */
 694   uint16_t config_size GNUNET_PACKED;
 695
 696   /* followed by gzip-compressed configuration of the peer */
 697
 698 };
 699
 700
 701 /**
 702  * Message to request configuration of a slave controller
 703  */
 704 struct GNUNET_TESTBED_SlaveGetConfigurationMessage
 705 {
 706   /**
 707    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIGURATION
 708    */
 709   struct GNUNET_MessageHeader header;
 710
 711   /**
 712    * The id of the slave host
 713    */
 714   uint32_t slave_id GNUNET_PACKED;
 715
 716   /**
 717    * Operation ID
 718    */
 719   uint64_t operation_id GNUNET_PACKED;
 720
 721 };
 722
 723
 724 /**
 725  * Reply to GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIG message
 726  */
 727 struct GNUNET_TESTBED_SlaveConfiguration
 728 {
 729   /**
 730    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SLAVE_CONFIGURATION
 731    */
 732   struct GNUNET_MessageHeader header;
 733
 734   /**
 735    * The id of the host where the slave is running
 736    */
 737   uint32_t slave_id GNUNET_PACKED;
 738
 739   /**
 740    * Operation ID
 741    */
 742   uint64_t operation_id GNUNET_PACKED;
 743
 744   /**
 745    * The size of the configuration when uncompressed
 746    */
 747   uint16_t config_size GNUNET_PACKED;
 748
 749   /* followed by gzip-compressed configuration of the peer */
 750
 751 };
 752
 753
 754 /**
 755  * Shutdown peers message
 756  */
 757 struct GNUNET_TESTBED_ShutdownPeersMessage
 758 {
 759   /**
 760    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
 761    */
 762   struct GNUNET_MessageHeader header;
 763
 764   /**
 765    * Operation ID
 766    */
 767   uint64_t operation_id GNUNET_PACKED;
 768 };
 769
 770
 771 /**
 772  * Message to start/stop services of a peer
 773  */
 774 struct GNUNET_TESTBED_ManagePeerServiceMessage
 775 {
 776   /**
 777    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
 778    */
 779   struct GNUNET_MessageHeader header;
 780
 781   /**
 782    * Unique ID of the peer whose service has to be managed.
 783    */
 784   uint32_t peer_id GNUNET_PACKED;
 785
 786   /**
 787    * Operation ID
 788    */
 789   uint64_t operation_id GNUNET_PACKED;
 790
 791   /**
 792    * set this to 1 to start the service; 0 to stop the service
 793    */
 794   uint8_t start;
 795
 796   /**
 797    * The NULL-terminated name of the service to start/stop follows here
 798    */
 799 };
 800
 801
 802 GNUNET_NETWORK_STRUCT_END
 803 #endif
 804 /* end of testbed.h */