/*	$Id: protocol.txt,v 1.8 2004/02/25 12:22:23 ola Exp $	*/

======================
PROTOCOL SPECIFICATION
======================

This document describes the protocol used for communication between
the uptime client (uptimec) and the server.


DOCUMENT INTRODUCTION
=====================

This document specifies the protocol used by clients to communicate with the
uptime-server. It is not a guide on how to write your own client, but it
outlines all that is needed to provide a full two-way communication with
the server.


VERSION
=======

This document specifies protocol version: 1


UDP/IP AND PORTS
================

Communication between the server and clients are done using datagrams
(UDP over IP packages) in a connectionless state.

The server listens for client requests on UDP port 2050. Port on client
side can be selected at random and will not affect the communication.


COMMUNICATION OVERVIEW
======================

Sessions between a client and the server is split into two phases. The
identification-phase and the update-phase.

--[ Login phase]--
1) Client sends LOGIN (0) command to server.
2) Server answers with LOGINOK (128) or LOGINFAILED (129)
 - On LOGINOK - Continue

--[ Update phase]--
3) The client sends an UPDATE (0) command.
4) The server answers with UPDATEOK or another relevent command.
5) Client waits for a full 10 minutes.
6) Client repeats from step three and sends a new update.



ENCAPSULATION STRUCTURE
=======================

All data sent between clients and the server are encapsulated in a given
structure. This structure contains a static header that describes the
content of the package, and the rest of the package is structured in
various ways based on the information found in the header.


MULTIBYTE INTEGERS
==================

All values that are stored in more than one byte needs to be encoded in
network byte order (Big-Endian).


PACKAGE HEADERS
===============

There are two different headers used, one for packages from clients to
the server, and another one used when the server communicates back to
it's clients.

CLIENT-TO-SERVER HEADER
------------------------
<-Prot Version-><-Command-><- Seq -><-Chksum-><-Host ID-><-Password-><-Data->
<-   1 byte   -><-1  byte-><-1byte-><-1 byte-><-4 bytes-><-16 bytes-><-....->

Prot Version
	Identifies the version of the protocol that this package has been
	formated to fit.

Command
	The command that this package contains.

Seq
	The sequence-number used by this package. Each package sent to the
	server shall have a unique sequence number, even resends. Client
	sequences MUST start on zero and increase by one for each package sent.
	When 255 is reached, the sequence starts over at zero. (Note: 255
	shall be included in the sequence aswell)

Checksum
	A checksum calculated with '(ProtVersion xor Command) xor Seq'. This
	is used to help detect valid packages from junk-data received.

Host ID
	A four byte integer in network byte order identifying the host
	sending this package.

Password
	Password in plain-text or as MD5-hash, depending on what the
	client-host supports. This is the hostpassword, which is different
	from the password used when logging in to the webgui for
	administration.

	If plain-text passwords are used, the remaining part of the password-
	block should be padded with zeros.

Data
	Data related to the command.

SERVER-TO-CLIENT HEADER
------------------------
<-Prot Version-><-Command-><-  Seq  -><-Checksum-><-Data->
<-   1 byte   -><-1  byte-><-1  Byte-><- 1 byte -><-....->

Prot Version
	Identifies the protocol version used. This is allways the same as the
	protocol specified by the client when the respons was triggered.

Command
	Server-to-Client command.

Seq
	Sequence-number. Each host has a unique sequence-counter.

Checksum
	Checksum calculated by ( ProtVersion xor Command ) xor Seq.
	Used to detect junk-data received.

Data
	Data related to the command.


CLIENT-TO-SERVER COMMANDS
=========================

These commands are sent from clients to the server.

LOGIN (0)
	This command performs a login towards the server. A respons shall be
	expected from the server in form of a LOGIN_OK (128) command. If no
	respons is received within 30 seconds, another LOGIN (0) attempt should
	be done. A total of five retries is allowed. If no reply is received in
	three tries, the client should sleep for 1800 seconds, and restart the
	login phase. (Unless client is instructed to not be persistant)
	
	Data:
		<-Client ID-><-Ver Major-><-Ver Minor-><-Ver Patch-> \
		<- 1  byte -><- 1  byte -><- 1  byte -><- 1  byte -> \
			<-  Len  -><- System Information                ->
			<-2 bytes-><- D y n a m i c                     ->
			           <-Sysname->\0<-Rel->\0<-Ver->\0<-Mach->


		Client ID
			Client identification, see below for more details.
		Ver Major
			Major version number of client
		Ver Minor
			Minor version number of client
		Ver Patch
			Patchnumber used by client
		Len
			Total length, in bytes, of block with system
			information
		System Information
			This block contains a set of fields with details
			about the client system. This information is
			extracted using the uname system call. Each field
			in this block is separated with a null-char (\0).

			Sysname
				Name of system running
				Max length: 32 bytes
			Rel
				System release
				Max length: 32 bytes
			Ver
				Version information
				Max length: 256 bytes
			Mach
				Systems hardware platform
				Max length: 32 bytes


LOGOUT (6)
	This is a command that can be used by clients to inform the server
	that they are shutting down. For example at a reboot or if the
	process is killed.

	Data:
		NO DATA


UPDATE (8)
	This command is the most commonly used command in a session between a
	client and the server. This command sends information to the server
	about current uptime and load on host.

	This command should be sent directly after a valid login has been
	confirmed by the server, and then resent every 600 seconds. Updates
	shall not be sent in shorter periods unless instructed to do so by
	the server.

	Data:
		<-Host Uptime-><-Load  1-><-Load  2-><-Load  3->
		<-  4 bytes  -><-2 bytes-><-2 bytes-><-2 bytes->

		Host Uptime
			Hosts uptime in seconds.
		Load 1
			Average number of processes in the system run queue
			over the last minute. Since this value is sent as an
			integer, it shall be calculated using: load * 100
			A value of 65535 shall be used if the average-load
			function is disabled in the client.
			Valid values are: 0 - 65500,65535
		Load 2
			Average number of processes in the system run queue
			over the five minutes. Since this value is sent as
			an integer, it shall be calculated using: load * 100
			A value of 65535 shall be used if the average-load
			function is disabled in the client.
			Valid values are: 0 - 65500,65535
		Load 3
			Average number of processes in the system run queue
			over the last fiftheen minutes. Since this value is
			sent as an integer, it shall be calculated using:
			A value of 65535 shall be used if the average-load
			function is disabled in the client.
			load * 100
			Valid values are: 0 - 65500,65535

		

SERVER-TO-CLIENT COMMANDS
=========================

The server has a set of commands that it can send to clients to inform them
of various various things, and to get them to performe some actions related
to the whole client-server relationship.

Commands from the server needs only to be expected after the client sent
commands to the server. The server will only answer requests and will never
send commands or data unless contacted by the server. Commands from the
server will be sent as soon as possible after receiving data from a client.

The client is responsible for making sure that the package is received from
the server that the original package was sent to.


LOGINOK (128)
	This command will be received from the server after a login-package
	has been sent containing valid account information. This command
	shall be expected from the server, and clients are not allowed to
	start sending updates before the server has validated their login.

	Data:
		NO DATA


LOGINFAILED (129)
	This command is used by the server as a respons to an invalid
	combination of hostid and password. Clients receiving this
	command shall inform the local user about the problem and exit.

	Data:
		NO DATA


UPDATEOK (136)
	The server uses this command to confirm that the last update has
	been received. However, there is no guarantee that the value has
	been inserted into the database when an UPDATEOK is sent, or that
	the client will receive this answer for all updates sent. UDP
	does not guarantee that sent packages will reach their receiver,
	so packages can get lost on the way, and the server has no way of
	knowing this. Also, in some cases, the server might even just skip
	sending this reply in case of high load. However, the server will
	do it's best to reply to all updates.

	The UPDATEOK command indicates that the server has received the
	last update, validated it's content and inserted it into the queue
	for database-updates.

	Data:
		NO DATA


UPDATEFAILED (137)
	This command is sent by the server in case the last update failed.
	This can be due to a bad package received or if the client is
	sending updates without being logged into the server.

	Data:
		NO DATA


REQUESTCHANGEDELAY (144)
	This command instructs clients to change the delay used between
	updates. A change can either be permanent or temporary. The server
	can use this command to spread it's load over the full time of
	a normal update period (in case many clients are sending their
	updates at the same time). It can also be used to temporary disable
	clients for a given time when, for example, the server needs to
	be upgraded to newer software.

	If this command is received as a reply to an UPDATE (8) command,
	it should be threated as an UPDATEOK (136) command.

	Data:
		<- Temporary -><- Delay ->
		<-  1  byte  -><-2 bytes->

		Temporary
			This value informs the client if this new delay
			should be used for the rest of the client's
			lifetime (or atleast until a new REQUESTCHANGEDELAY
			(144) command is received) or if it's just to be
			used for the next period.
			A value of zero defines that the delay is permanent
			and should be used for all loops.
			If non-zero is used, the client shall reset it's
			timer and wait the given delay before sending the
			next package. After the next package has been sent,
			the client shall restore it's last permanent delay.
		Delay
			The delay, in seconds, to wait before sending the
			next update. Valid values are: 30-65535.


REQUESTRELOGIN (152)
	This command is used by a server to instruct the client that it
	should should send a new login-request to the server and wait for
	a LOGINOK (128) command. This command can, for example, be used by
	the server to re-identify running clients that cached information
	has been lost about. Loss of cached information can be caused by a
	server restart or if the client isn't heard from within a given
	time and therefor flushed from the cache. Note however that the
	information is still stored in the servers database, it's just not
	in it's active cache.

	If this command is received as a reply to an UPDATE (8) command,
	it shall also be threated as an UPDATEFAILED (137) command.

	Data:
		NO DATA


REQUESTHARDRELOGIN (153)
	This command is similar to REQUESTRELOGIN (152) but does also
	require the client to resolv the hostname again, and send any
	furture packages to the IP address resolved.

	If <-Length-> below is zero, the client shall resolv the ip for
	the serveraddress that was provided at startup. If an argument
	is given, it should be used as a new host address to resolv and
	use for any following communications.

	If <-Length-> is zero, the trailing \0 will be omitted by the
	server.

	Data:
		<-Length-><- Argument ->\0
		<-1 byte-><- ........ ->

		Length
			The length, in bytes, of the argument, includning
			the trailing \0-char.
		Argument
			Null-terminated string containint thenNew server
			address to resolv and continue sending updates to.


REQUESTSHUTDOWN (160)
	A faulty or missbehaving client can cause increased load on the
	server, which in turn affects the overall usability of the project.
	Therefor, the server has this command that can be used to instruct
	clients to shutdown immediately without any furture updates or
	commands.

	If this command isn't honored by the client, the host may be banned
	from using the uptime-project. Also, if a faulty client continues to
	cause problems, the entire account might be disabled and banned to
	minimize the problems caused for other users.


MSGNOTICE (168)
	This command is used to send text-messages to the client that should,
	in some way, be displayed to the user that owns the process. These
	messages arn't critical and can be ignored by the user. The client
	however is required to display these messages, and may not ignore
	them.

	Data:
		<-Length-><-Message->\0
		<-1 byte-><-.......->

		Length
			The length of the message in bytes, not including
			the trailing null-char. Valid values are between
			one and 255.
		Message
			The message to present the user with.


MSGCRITICAL (169)
	These messages contain critical information that the client must do
	all in it's power to inform the user about.

	Data:
		<-Length-><-Message->\0
		<-1 byte-><-.......->

		Length
			The length of the message in bytes, not including
			the trailing null-char. Valid values are between
			one and 255.
		Message
			The message to to display.



PASSWORD ENCRYPTION
===================

The client has the option to encrypt it's passwords using MD5-digests
instead of sending them in plain text. If using MD5-digests, they shall
be sent as 16-byte hashes without convertion to printable version.

The server will detect the type of password used without any interaction
from the client.


SERVER IDENTIFICATION
=====================

Clients shall identify all received packages by making sure that they
arrive from the same address and port that the original LOGINOK (128)
package was sent. Packages originating from other addresses/ports shall
be ignored by the client.


CLIENT ID'S
===========

Clients are assigned ID's to help detect problems with clients written by
various people for different platforms.

The following ID's have been allocated:
0   - Reserved
1   - mrEriksson's UN*X client
255 - Generic ID that can be used for tests and development of new
      clients.

ID's for a new client can be requested by contacting the uptime-project at
http://www.mrEriksson.net.


MORE INFORMATION
================

More information about this protocol, the uptime-project and the mrEriksson
Network can be found at http://www.mrEriksson.net


AUTHOR
======

This protocol is designed and developed by Ola Eriksson. For more information
contact author via e-mail to ola(at)mrEriksson.net.


COPYRIGHT
=========

Copyright (c) 2003-2004 Ola Eriksson, All Rights Reserved
