Wire protocol

Organizers do not need this page to run an event. It is here to read a packet capture, or to check what a version change touches.

Framing

Every link is one TCP connection, wrapped in TLS when VNET_TLS=1. It carries frames:

+----------------------+------------------+---------------------------+
| payload size, uint32 | type, uint16     | payload (size bytes)      |
| network byte order   | network order    |                           |
+----------------------+------------------+---------------------------+

The header is 6 bytes. A payload is at most 65994 bytes (a 66000-byte buffer less the header); a frame that announces more closes the connection. IPV4_RAW carries an IPv4 packet as it is; HEARTBEAT has no payload; every other type carries a protobuf message defined in proto/mip.proto.

Message types

Numbers are fixed for the life of the protocol; a removed number is not reused.

Type	Name	Direction	Purpose
0	HEARTBEAT	every link	keeps the link alive
1	SWITCH_MIP	switch to conductor	registration: name, key, port, network, advertised address, config fingerprint
2	AGENT_MIP	agent to conductor	join: name, key, network
3	CONNECT_TO_SWITCH	conductor to agent	the switch to use and a one-time token
4	AGENT_CONNECTION_TOKEN	conductor to switch	the agent name that goes with the token
5	AUTH_CONNECT_TO_SWITCH	agent to switch	the token
6	CONNECTION_ACCEPTED	switch to agent	the virtual address
7	AGENT_MRP	agent to conductor	reconnects the control link of an agent that kept its switch
8, 9	unused
10	IPV4_RAW	agent and switch, switch and switch	one IPv4 packet
11	AGENT_REGISTERED	switch to conductor	an agent attached to this switch
12	SWITCH_ROUTE_UPDATE	conductor to switch	the switch that holds a virtual address
13	SWITCH_DISCONNECTED	conductor to switch	a switch left; drop its routes
14	SWITCH_HELLO	switch to switch	opens a peer link, with the pair’s token
15	AGENT_UNREGISTERED	switch to conductor, conductor to switch	an agent left; withdraw its route
16	PEER_TOKEN	conductor to switch	the token a pair of switches uses to link
17	SWITCH_CONFIG	switch to conductor	the fingerprint of the config the switch applies
18	CONFIG_PUSH	conductor to switch	one piece of the switch config (at most 60000 bytes of text), with its index, a last-piece flag and the fingerprint

The order of the join messages is shown in How a machine joins.

Rules a program enforces

• A connection must identify itself (SWITCH_MIP, AGENT_MIP, AGENT_MRP, AUTH_CONNECT_TO_SWITCH or SWITCH_HELLO) within 10 seconds, or it is closed.

• A second identification on an identified connection is refused.

• A switch accepts tokens, routes and configs only on its conductor link.

• A switch accepts IPV4_RAW only from an authenticated agent or a peer switch.

• With TLS, the role in the peer certificate must match the role the connection claims.