The Uptimes Protocol (rev. 5.0)

What is this document about?
This document will describe the 5th revision of the uptimes protocol,
used to communicate between the uptime client and the server.

Overview
There are two protocols supported by the uptime server. The primary
protocol (which should be used by all clients that aren't behind a
proxy) uses UDP to send client data to the server. The backup protocol
uses HTTP and can be tunneled through an HTTP proxy server. This
document describes the UDP protocol. For information on the HTTP
protocol, look at <http://uptimes.wonko.com/oldprotocol.php>.

Client Requirements
In order to meet the specifications of this protocol, a client must:

 * Use UDP to send uptime reports
 * Send the uptime at most once every 30 seconds
 * Send the uptime at least once every 10 minutes
 * Meet the protocol specifications detailed below

Sending the Report
Uptime reports should be sent via UDP to uptimes.wonko.com on port
49153. The structure of the report is just a simple string, formatted
like this:

authkey|uptime|load|idle|os|oslevel|cpu|client

So, Wonko's Uptime Client might send the following string:

51cbb9711de405x06a877z75404be027|415|100.00|0|Windows|2000|i686|WonkoClient/2.1.0

If your client doesn't support CPU load or idle, you could leave those
sections blank, like so:

51cbb9711de405x06a877z75404be027|415|||Windows|2000|i686|WonkoClient/2.1.0

Now, here's a description of each piece of data:

 * authkey (required)
   This is a 32-character key that is unique for each host. The key for
   each host can be found on the host details page after the host is
   registered.
 * uptime (required)
   Uptime in minutes of the host.
 * load
   A value describing the actual CPU load of the host as a percentage
   from 0 to 100, in the form '100.00'.
 * idle
   This describes the percentage of the total uptime that the host was
   completely idle. The value can vary from '0' to '100'. It should be
   noted that this is an all-inclusive calculation, and it should
   represent the total cumulative percentage of time that the host has
   been idle, not just the percentage of idle CPU time as the current
   moment.
 * os (required)
   Operating system or platform of the host. This should be a string no
   longer than 32 characters. It should be one of the values below.
    o AIX
    o BeOS
    o BSDi
    o Darwin
    o Embedded
    o FreeBSD
    o HPLaser
    o HPUX
    o IRIX
    o IRIX64
    o Linux
    o MacOS
    o NetBSD
    o Netware
    o OpenBSD
    o OpenVMS
    o QNX
    o RiscRouter
    o SunOS
    o TINI OS
    o Ultrix
    o Unixware
    o Windows
   (For additions, email <ryan@wonko.com>)
 * oslevel (required)
   Version of the host's operating system. Examples are "2.0.37", "XP",
   "4.11".
 * cpu
   This key describes the CPU of the machine. You are advised, but not
   restricted, to use one of the following strings:
    o alpha
    o DS80C390
    o i386
    o i486
    o i586
    o i686
    o MIPS
    o pa-risc
    o ppc
    o sparc
    o sun4m
    o sun4c
    o sun4u
    o VAX
   (For additions, email <ryan@wonko.com>)
 * client
   This is an optional string, no longer than 32 characters, the
   describes the client. Usually it should be the client's name and
   version number, and optionally the version number of the protocol the
   client supports. Wonko's Uptime Client sends the string
   WonkoClient/2.1.0.

Return Values
Since UDP is a sessionless protocol, the server will not send a message
back when you send a report. You'll just have to hope you got the data
formatted right. In order to be at least a little helpful, I've added a
field called "Last Error" to the host details page of hosts that you
own. Assuming you at least send the correct authkey, this field will be
updated to contain the latest status or error message from the server.

Faking
Now that you know the protocol, it's easy to write a client that fakes
its uptime. Personally, I think hosts running FreeBSD 4.6.2 with uptimes
over 3 years are pretty stupid. Maybe you think differently. In any
case, hosts with fake uptimes will be marked bogus and ignored in the
statistics, so there's really no point in wasting your time.

Uptimes Protocl (rev. 5.0) - 09/09/2002, <ryan@wonko.com>
 
Copyright © 2002 Ryan Grove. All rights reserved.