2 This file is part of GNUnet
3 Copyright (C) 2008--2013 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @file testbed/testbed.h
23 * @brief IPC messages between testing API and service ("controller")
24 * @author Christian Grothoff
30 #include "gnunet_util_lib.h"
32 GNUNET_NETWORK_STRUCT_BEGIN
34 * Initial message from a client to a testing control service.
36 struct GNUNET_TESTBED_InitMessage
39 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_INIT
41 struct GNUNET_MessageHeader header;
44 * Host ID that the controller is either given (if this is the
45 * dominating client) or assumed to have (for peer-connections
46 * between controllers). A controller must check that all
47 * connections make consistent claims...
49 uint32_t host_id GNUNET_PACKED;
52 * Event mask that specifies which events this client
53 * is interested in. In NBO.
55 uint64_t event_mask GNUNET_PACKED;
57 /* Followed by 0-terminated hostname of the controller */
62 * Notify the service about a host that we intend to use.
64 struct GNUNET_TESTBED_AddHostMessage
67 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST
69 struct GNUNET_MessageHeader header;
72 * Unique ID for the host (in NBO).
74 uint32_t host_id GNUNET_PACKED;
77 * SSH port to use, 0 for default (in NBO).
79 uint16_t ssh_port GNUNET_PACKED;
82 * Number of bytes in the user name that follows;
83 * 0 to use no user name; otherwise 'strlen (username)',
84 * excluding 0-termination!
86 uint16_t username_length GNUNET_PACKED;
89 * Number of bytes in the host name (excluding 0-termination) that follows the
90 * user name; cannot be 0
92 uint16_t hostname_length GNUNET_PACKED;
95 * The length of the uncompressed configuration
97 uint16_t config_size GNUNET_PACKED;
99 /* followed by non 0-terminated user name */
101 /* followed by non 0-terminated host name */
103 /* followed by gzip compressed configuration to start or connect to a
104 controller on this host. While starting the controller this configuration
105 is used as a template */
110 * Confirmation from the service that adding a host
111 * worked (or failed).
112 * FIXME: Where is this required?
114 struct GNUNET_TESTBED_HostConfirmedMessage
117 * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST_SUCCESS
119 struct GNUNET_MessageHeader header;
122 * Unique ID for the host (in NBO).
124 uint32_t host_id GNUNET_PACKED;
126 /* followed by the 0-terminated error message (on failure)
127 * (typical errors include host-id already in use) */
132 * Client notifies controller that it should delegate
133 * requests for a particular client to a particular
136 struct GNUNET_TESTBED_ControllerLinkRequest
139 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS
141 struct GNUNET_MessageHeader header;
144 * For which host should requests be delegated? NBO.
146 uint32_t delegated_host_id GNUNET_PACKED;
149 * The id of the operation which created this message
151 uint64_t operation_id GNUNET_PACKED;
154 * Which host is responsible for managing the delegation? NBO
156 uint32_t slave_host_id GNUNET_PACKED;
159 * Set to 1 if the receiving controller is the master controller for
160 * the slave host (and thus responsible for starting it?). 0 if not
162 uint8_t is_subordinate;
167 * Response message for ControllerLinkRequest message
169 struct GNUNET_TESTBED_ControllerLinkResponse
172 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS_RESULT
174 struct GNUNET_MessageHeader header;
177 * The size of the compressed configuration. Can be ZERO if the controller is
178 * not started (depends on the ControllerLinkRequest). NBO.
180 uint16_t config_size GNUNET_PACKED;
183 * Set to #GNUNET_YES to signify SUCCESS; #GNUNET_NO to signify failure
185 uint16_t success GNUNET_PACKED;
188 * The id of the operation which created this message. NBO
190 uint64_t operation_id GNUNET_PACKED;
192 /* If controller linking is successful and configuration is present, then here
193 * comes the serialized gzip configuration with which the controller is
194 * running at the delegate host */
196 /* In case of failure, here comes the error message (without \0 termination)*/
201 * Message sent from client to testing service to
202 * create (configure, but not start) a peer.
204 struct GNUNET_TESTBED_PeerCreateMessage
207 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER
209 struct GNUNET_MessageHeader header;
212 * On which host should the peer be started?
214 uint32_t host_id GNUNET_PACKED;
217 * Unique operation id
219 uint64_t operation_id GNUNET_PACKED;
222 * Unique ID for the peer.
224 uint32_t peer_id GNUNET_PACKED;
227 * Size of the uncompressed configuration
229 uint16_t config_size GNUNET_PACKED;
231 /* followed by serialized peer configuration;
232 * gzip'ed configuration file in INI format */
237 * Message sent from client to testing service to
238 * reconfigure a (stopped) a peer.
240 struct GNUNET_TESTBED_PeerReconfigureMessage
243 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_RECONFIGURE_PEER
245 struct GNUNET_MessageHeader header;
248 * Unique ID for the peer.
250 uint32_t peer_id GNUNET_PACKED;
253 * Operation ID that is used to identify this operation.
255 uint64_t operation_id GNUNET_PACKED;
258 * The length of the serialized configuration when uncompressed
260 uint16_t config_size GNUNET_PACKED;
262 /* followed by serialized peer configuration;
263 * gzip'ed configuration file in INI format */
268 * Message sent from client to testing service to
271 struct GNUNET_TESTBED_PeerStartMessage
274 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_START_PEER
276 struct GNUNET_MessageHeader header;
279 * Unique ID for the peer.
281 uint32_t peer_id GNUNET_PACKED;
284 * Operation ID that is used to identify this operation.
286 uint64_t operation_id GNUNET_PACKED;
291 * Message sent from client to testing service to
294 struct GNUNET_TESTBED_PeerStopMessage
297 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_STOP_PEER
299 struct GNUNET_MessageHeader header;
302 * Unique ID for the peer.
304 uint32_t peer_id GNUNET_PACKED;
307 * Operation ID that is used to identify this operation.
309 uint64_t operation_id GNUNET_PACKED;
314 * Message sent from client to testing service to
315 * destroy a (stopped) peer.
317 struct GNUNET_TESTBED_PeerDestroyMessage
320 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_DESTROY_PEER
322 struct GNUNET_MessageHeader header;
325 * Unique ID for the peer.
327 uint32_t peer_id GNUNET_PACKED;
330 * Operation ID that is used to identify this operation.
332 uint64_t operation_id GNUNET_PACKED;
337 * Message sent from client to testing service to
338 * (re)configure a "physical" link between two peers.
340 struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage
343 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_CONFIGURE_UNDERLAY_LINK
345 struct GNUNET_MessageHeader header;
348 * 'enum GNUNET_TESTBED_ConnectOption' of the option to change
350 int32_t connect_option GNUNET_PACKED;
353 * Unique ID for the first peer.
355 uint32_t peer1 GNUNET_PACKED;
358 * Unique ID for the second peer.
360 uint32_t peer2 GNUNET_PACKED;
363 * Operation ID that is used to identify this operation.
365 uint64_t operation_id GNUNET_PACKED;
367 /* followed by option-dependent variable-size values */
372 * Message sent from client to testing service to
375 struct GNUNET_TESTBED_OverlayConnectMessage
378 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_OVERLAY_CONNECT
380 struct GNUNET_MessageHeader header;
383 * Unique ID for the first peer.
385 uint32_t peer1 GNUNET_PACKED;
388 * Operation ID that is used to identify this operation.
390 uint64_t operation_id GNUNET_PACKED;
393 * Unique ID for the second peer.
395 uint32_t peer2 GNUNET_PACKED;
398 * The ID of the host which runs peer2
400 uint32_t peer2_host_id GNUNET_PACKED;
405 * Message sent from host controller of a peer(A) to the host controller of
406 * another peer(B) to request B to connect to A
408 struct GNUNET_TESTBED_RemoteOverlayConnectMessage
411 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT
413 struct GNUNET_MessageHeader header;
418 uint32_t peer GNUNET_PACKED;
421 * The Operation ID that is used to identify this operation
423 uint64_t operation_id GNUNET_PACKED;
428 struct GNUNET_PeerIdentity peer_identity;
431 * To be followed by the HELLO message of A
433 struct GNUNET_MessageHeader hello[0];
434 // FIXME: we usually do not use this gcc-hack as some
435 // compilers / tools really get messed up by it...
440 * Event notification from a controller to a client.
442 struct GNUNET_TESTBED_PeerEventMessage
445 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_PEER_EVENT
447 struct GNUNET_MessageHeader header;
450 * `enum GNUNET_TESTBED_EventType` (in NBO);
451 * either #GNUNET_TESTBED_ET_PEER_START or #GNUNET_TESTBED_ET_PEER_STOP.
453 int32_t event_type GNUNET_PACKED;
456 * Host where the peer is running.
458 uint32_t host_id GNUNET_PACKED;
461 * Peer that was started or stopped.
463 uint32_t peer_id GNUNET_PACKED;
466 * Operation ID that is used to identify this operation.
468 uint64_t operation_id GNUNET_PACKED;
473 * Event notification from a controller to a client.
475 struct GNUNET_TESTBED_ConnectionEventMessage
478 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONNECT_EVENT
480 struct GNUNET_MessageHeader header;
483 * 'enum GNUNET_TESTBED_EventType' (in NBO);
484 * either #GNUNET_TESTBED_ET_CONNECT or #GNUNET_TESTBED_ET_DISCONNECT.
486 int32_t event_type GNUNET_PACKED;
491 uint32_t peer1 GNUNET_PACKED;
496 uint32_t peer2 GNUNET_PACKED;
499 * Operation ID that is used to identify this operation.
501 uint64_t operation_id GNUNET_PACKED;
506 * Event notification from a controller to a client.
508 struct GNUNET_TESTBED_OperationFailureEventMessage
511 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_OPERATION_FAIL_EVENT
513 struct GNUNET_MessageHeader header;
516 * 'enum GNUNET_TESTBED_EventType' (in NBO);
517 * #GNUNET_TESTBED_ET_OPERATION_FINISHED.
519 int32_t event_type GNUNET_PACKED;
522 * Operation ID of the operation that created this event.
524 uint64_t operation_id GNUNET_PACKED;
526 /* followed by 0-terminated error message */
531 * Event notification from a controller to a client.
533 struct GNUNET_TESTBED_PeerCreateSuccessEventMessage
536 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER_SUCCESS
538 struct GNUNET_MessageHeader header;
541 * Peer identity of the peer that was created.
543 uint32_t peer_id GNUNET_PACKED;
546 * Operation ID of the operation that created this event.
548 uint64_t operation_id GNUNET_PACKED;
553 * Event notification from a controller to a client for
554 * a generic operational success where the operation does
555 * not return any data.
557 struct GNUNET_TESTBED_GenericOperationSuccessEventMessage
560 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_GENERIC_OPERATION_SUCCESS
562 struct GNUNET_MessageHeader header;
565 * 'enum GNUNET_TESTBED_EventType' (in NBO);
566 * #GNUNET_TESTBED_ET_OPERATION_FINISHED.
568 int32_t event_type GNUNET_PACKED;
571 * Operation ID of the operation that created this event.
573 uint64_t operation_id GNUNET_PACKED;
578 * Message sent from client to testing service to
579 * obtain the configuration of a peer.
581 struct GNUNET_TESTBED_PeerGetConfigurationMessage
584 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_GET_PEER_INFORMATION
586 struct GNUNET_MessageHeader header;
589 * Unique ID for the peer.
591 uint32_t peer_id GNUNET_PACKED;
594 * Operation ID that is used to identify this operation.
596 uint64_t operation_id GNUNET_PACKED;
601 * Peer configuration and identity reply from controller to a client.
603 struct GNUNET_TESTBED_PeerConfigurationInformationMessage
606 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_PEER_INFORMATION
608 struct GNUNET_MessageHeader header;
611 * The id of the peer relevant to this information
613 uint32_t peer_id GNUNET_PACKED;
616 * Operation ID of the operation that created this event.
618 uint64_t operation_id GNUNET_PACKED;
621 * Identity of the peer.
623 struct GNUNET_PeerIdentity peer_identity;
626 * The size of configuration when uncompressed
628 uint16_t config_size GNUNET_PACKED;
630 /* followed by gzip-compressed configuration of the peer */
635 * Message to request configuration of a slave controller
637 struct GNUNET_TESTBED_SlaveGetConfigurationMessage
640 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIGURATION
642 struct GNUNET_MessageHeader header;
645 * The id of the slave host
647 uint32_t slave_id GNUNET_PACKED;
652 uint64_t operation_id GNUNET_PACKED;
657 * Reply to #GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIGURATION message
659 struct GNUNET_TESTBED_SlaveConfiguration
662 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_SLAVE_CONFIGURATION
664 struct GNUNET_MessageHeader header;
667 * The id of the host where the slave is running
669 uint32_t slave_id GNUNET_PACKED;
674 uint64_t operation_id GNUNET_PACKED;
677 * The size of the configuration when uncompressed
679 uint16_t config_size GNUNET_PACKED;
681 /* followed by gzip-compressed configuration of the peer */
686 * Shutdown peers message
688 struct GNUNET_TESTBED_ShutdownPeersMessage
691 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
693 struct GNUNET_MessageHeader header;
698 uint64_t operation_id GNUNET_PACKED;
703 * Message to start/stop services of a peer
705 struct GNUNET_TESTBED_ManagePeerServiceMessage
708 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
710 struct GNUNET_MessageHeader header;
713 * Unique ID of the peer whose service has to be managed.
715 uint32_t peer_id GNUNET_PACKED;
720 uint64_t operation_id GNUNET_PACKED;
723 * set this to 1 to start the service; 0 to stop the service
728 * The NULL-terminated name of the service to start/stop follows here
734 * Message to send underlay link model of a peer. This message will be
735 * forwarded to the controller running the peer.
737 struct GNUNET_TESTBED_UnderlayLinkModelMsg
740 * Type is #GNUNET_MESSAGE_TYPE_UNDERLAYLINKMODELMSG
742 struct GNUNET_MessageHeader header;
745 * The number of peer entries contained in this message
747 uint32_t nentries GNUNET_PACKED;
750 * The number of link properties contained in this message
752 uint32_t nprops GNUNET_PACKED;
755 * Array of ids of peers to be in the blacklist/whitelist. Each id is of type
756 * uint32_t. Number of ids should be equal to nentries.
760 * Array of link properties. Each link property is to be arraged in a
761 * sequence of four integers of type uint32_t: peer_id, latency, loss and
767 /**************************************/
768 /* Barriers IPC messages and protocol */
769 /**************************************/
773 * The environmental variable which when available refers to the configuration
774 * file the local testbed controller is using
776 #define ENV_TESTBED_CONFIG "GNUNET_TESTBED_CONTROLLER_CONFIG"
780 * Message to initialise a barrier
782 struct GNUNET_TESTBED_BarrierInit
785 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT
787 struct GNUNET_MessageHeader header;
790 * The quorum percentage needed for crossing the barrier
795 * name of the barrier. Non NULL-terminated.
802 * Message to cancel a barrier
804 struct GNUNET_TESTBED_BarrierCancel
807 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_CANCEL
809 struct GNUNET_MessageHeader header;
812 * The barrier name. Non NULL terminated
819 * Message for signalling status changes of a barrier
821 struct GNUNET_TESTBED_BarrierStatusMsg
824 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS
826 struct GNUNET_MessageHeader header;
829 * status. Use enumerated values of enum BarrierStatus
831 uint16_t status GNUNET_PACKED;
834 * strlen of the barrier name
836 uint16_t name_len GNUNET_PACKED;
839 * the barrier name (0-terminated) concatenated with an error message
840 * (0-terminated) if the status were to indicate an error
847 * Message sent from peers to the testbed-barrier service to indicate that they
848 * have reached a barrier and are waiting for it to be crossed
850 struct GNUNET_TESTBED_BarrierWait
853 * Type is #GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT
855 struct GNUNET_MessageHeader header;
858 * The name of the barrier they have reached. Non-NULL terminated.
864 GNUNET_NETWORK_STRUCT_END
866 /* end of testbed.h */