The Argo server is a simple daemon which listens upon a network socket and accepts client commands.

This page documents the protocol which is used by clients to communicate with the server.

The API which the network server uses is deliberately designed to be very simple, and easy to work with. The protocol is line-orientated, with each client-request being of the form "command arg1 arg2 arg3 .. argN". (Internally each command word is implemented by a different plugin.)

When the server recieves a command from the client it will acknowlege it with one of the following return codes:

200 [comment]  - Command accepted
300 [comment]  - End of command output
400 [comment]  - Error

As you can see there are three different codes in use at the moment:

• 200 + optional comment
  • This is sent by the server when a command has been accepted.
• 300 + optional comment
  • This denotes the end of the servers output for this command.
• 400 + optional comment
  • This denotes an error.

In the normal course of a connection the exchange is assumed to look like this:

• Client sends a command. "list available"
• Server sends OK message "200 OK"
• Server outputs additional text. "one, two, three"
• Server ouptuts end message "300 DONE"

At any point the server may send an error message "400 ERROR" which denotes the end of this command.

As an example here we'll list all installed Xen instances:

skx@lappy:~$ telnet itchy 20203
Trying 192.168.1.50...
Connected to itchy.
Escape character is '^]'.
list available
200 OK
lj       < This is a Xen instance with the name 'lj'
builder  < This is a Xen instance with the name 'builder'
test     < This is a Xen instance with the name 'test'
dev      < This is a Xen instance with the name 'dev'
300 END

To pause a machine we need to authenticate:

skx@lappy:~$ telnet itchy 20203
Trying 192.168.1.50...
Connected to itchy.
Escape character is '^]'.
pause lj
400 NOT AUTHENTICATED

For a client to authenticate itself it should use the "auth" command, along with a username and password. The server will compare these values to those set in its configuration file /etc/argo-server/argo-server.conf.

kx@lappy:~$ telnet itchy 20203
Trying 192.168.1.50...
Connected to itchy.
Escape character is '^]'
auth steve steve
200 OK
300 DONE

pause lj
200 OK
300 DONE

exit
200 OK
300 DONE

Note: it is possible to add accounts which are only allowed to control a particular virtual host. This makes it possible for you to allow a Xen "owner" to control their own instance without them being able to reboot/pause/shutdown your own instances. If a user attempts to perform an action for which they have no permission it will be denied :)

(Users who do not have permission to modify a particular instance will not have those instances displayed when they use the "list running", or "list available" commands.)

Here is an example of a user steve attempting to pause an instance which they are not allowed to modify:

skx@itchy:$ telnet localhost 20203
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
auth steve steve  <- Authenticate
200 OK
300 DONE 
list available    <- List available instances
200 OK
lj                <- Several available instances
one.my.flat
three.my.flat
two.my.flat
300 DONE
pause lj          <- Attempt to pause somebody elses instance.
400 NOT ALLOWED   <- Request denied.

Protocol Primitives / Available Commands

This is a list of the currently implemented primitives. There is certainly room for more to be added. I think the obvious missing ones are:

• System load indicator(s)
• Query of the images file system type / loopback / lvm / size etc.

dmesg            > Show the DMESG output of the Xen host.
exit             > Disconnect
info    name     > Give information on the Xen instance called 'name'
ip      name     > Show the IP address of the given host.
mac     name     > Show the MAC address of the given host.
nop              > Keep the connection open.
pause   name     > Pause the Xen instance called 'name'
reboot  name     > Reboot the given running instance.
start   name     > Start a Xen instance called 'name'
stop    name     > Stop the running instance with the name 'name'
tx      name     > Show network traffic transmitted by this host.
rx      name     > Show network traffic recieved by this host.
unpause name     > Unpause the  Xen instance called 'name'
uptime  name     > Show the uptime for the Xen instance called 'name'
list available   > List all available xen instances.
list running     > List all running xen instances.
exit             > Disconnect.
help             > Give brief help information

Each command is implemented in a dynamically loaded plugin, see /usr/share/perl5/Xen/Monitor/Plugins for examples. Adding new ones should be fairly trivial for somebody comfortable with Perl.

A plugin can contain a number of different commands if you wish. See start.pm for an example of that.