Vde management protocol
From VirtualSquare
This page provide a (minimal) documentation about the vde management protocol.
This is the protocol used on management connections by vde_switch and wirefilter, but future tools may decide to use the same protocol. The tools with specific options provide UNIX sockets for management which use this profocol.
The protocol is ascii based and has numerical codes to simplify post-processing. It has similarities with SMTP. It is possible to have direct terminal connections to the management port using (for example):
socat READLINE unix:/path/of/mgmt/socket
where /path/of/mgmt/socket is the pathname of the management socket of an existing vde switch, i.e. of a vde_switch or a wirefilter started with the following option:
-M /path/of/mgmt/socket
The tool starts the communication with a greeting header and then the prompt:
VDE switch V.2.2.1 (C) Virtual Square Team (coord. R. Davoli) 2005,2006,2007 - GPLv2 vde$
The prompt is a line ending with "$ " (the dollar sign and a blank). Please note that the prompt line has no line feed at the end. Line ending in "$ " should not appear anywhere else in the greeting header. The prompt message is repeated after each command.
The user (or the client program, we will say just user in the following part of the section including both cases) send commands. Each char is remotely echoed.
Management messages always begin with a 4 digits code. If the first digit is 1, the message is the result of a command, 3 is for asynchronous messages, like debug logs, 0000 is for multi-line output.
Each command has exactly one result message reply.
vde$ port/sethub 0 1000 Success vde$ pirt 1038 Function not implemented
1000 is the code for success, otherwise the code is the sum of 1000 and the errno code of the error.
When a command need to return a long reply, the protocol uses the code 0000
vde$ help 0000 DATA END WITH '.' COMMAND PATH SYNTAX HELP ------------ -------------- ------------ ds ============ DATA SOCKET MENU ds/showinfo show ds info help [arg] Help (limited to arg when specified) ........ vlan/allprint [N] print the list of defined vlan (including inactive port) . 1000 Success vde$
The long reply starts on the line following 0000 and terminates by a line containing exactly one dot.
Codes having 3 as their first digit are for asyncronous messages. For example if the user has activated some debug notifications, the messages get sent as lines starting with 3xxx codes.
vde$ debug/add 1000 Success vde$ 3032 port/ep/- Port 02 FD 12 3022 port/- 02
Please note that debug messages can arrive at any time. They can arrive during the input of a command, or interleaved with the output. Entire lines of output and asyncronous messages can interleave in any order, in no cases aynchronous message appear inside a 0000 output.
The commands can have a pathname structure. Many tools (like the vdehist library) use the "help" command to have a list of available commands and implement command completion.
The output structure of help should be like the following:
vde$ help 0000 DATA END WITH '.' COMMAND PATH SYNTAX HELP ------------ -------------- ------------ ds ============ DATA SOCKET MENU ds/showinfo show ds info help [arg] Help (limited to arg when specified) logout logout from this mgmt terminal shutdown shutdown of the switch showinfo show switch version and info load path load a configuration script debug ============ DEBUG MENU debug/list list debug categories debug/add dbgpath enable debug info for a given category debug/del dbgpath disable debug info for a given category plugin ============ PLUGINS MENU plugin/list list plugins plugin/add library load a plugin plugin/del name unload a plugin ...... vlan/allprint [N] print the list of defined vlan (including inactive port) .
Syntax and help field get used by vdetelweb to create automatically the web interface.
