/* $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