1THE UPTIMES PROTOCOL (rev. 5.0) http://uptimes.wonko.com/protocol.php
2=====================================================================
3
4
5What is this document about?
6----------------------------
7This document will describe the 5th revision of the uptimes protocol,
8used to communicate between the uptime client and the server.
9
10
11Overview
12--------
13There are two protocols supported by the uptime server. The primary
14protocol (which should be used by all clients that aren't behind a
15proxy) uses UDP to send client data to the server. The backup protocol
16uses HTTP and can be tunneled through an HTTP proxy server. This
17document describes the UDP protocol. For information on the HTTP
18protocol, look at <http://uptimes.wonko.com/oldprotocol.php>.
19
20
21Client Requirements
22-------------------
23In order to meet the specifications of this protocol, a client must:
24
25 * Use UDP to send uptime reports
26 * Send the uptime at most once every 30 seconds
27 * Send the uptime at least once every 10 minutes
28 * Meet the protocol specifications detailed below
29
30
31Sending the Report
32------------------
33Uptime reports should be sent via UDP to uptimes.wonko.com on port
3449153. The structure of the report is just a simple string, formatted
35like this:
36
37    authkey|uptime|load|idle|os|oslevel|cpu|client
38
39So, Wonko's Uptime Client might send the following string:
40
41    51cbb9711de405x06a877z75404be027|415|100.00|0|Windows|2000|i686|WonkoClient/2.1.0
42
43If your client doesn't support CPU load or idle, you could leave those
44sections blank, like so:
45
46    51cbb9711de405x06a877z75404be027|415|||Windows|2000|i686|WonkoClient/2.1.0
47
48
49Now, here's a description of each piece of data:
50
51
52 * authkey (required)
53   This is a 32-character key that is unique for each host. The key
54   for each host can be found on the host details page after the host
55   is registered.
56
57 * uptime (required)
58   Uptime in minutes of the host.
59
60 * load
61   A value describing the actual CPU load of the host as a percentage
62   from 0 to 100, in the form '100.00'.
63
64 * idle
65   This describes the percentage of the total uptime that the host was
66   completely idle. The value can vary from '0' to '100'.  It should
67   be noted that this is an all-inclusive calculation, and it should
68   represent the total cumulative percentage of time that the host has
69   been idle, not just the percentage of idle CPU time as the current
70   moment.
71
72 * os (required)
73   Operating system or platform of the host. This should be a string
74   no longer than 32 characters. It should be one of the values below.
75
76   - AIX
77   - BeOS
78   - BSDi
79   - Darwin
80   - Embedded
81   - FreeBSD
82   - HPLaser
83   - HPUX
84   - IRIX
85   - IRIX64
86   - Linux
87   - MacOS
88   - NetBSD
89   - Netware
90   - OpenBSD
91   - OpenVMS
92   - QNX
93   - RiscRouter
94   - SunOS
95   - TINI OS
96   - Ultrix
97   - Unixware
98   - VAX
99   - Windows
100
101(For additions, email <ryan@wonko.com>)
102
103 * oslevel (required)
104   Version of the host's operating system. Examples are "2.0.37",
105   "XP", "4.11".
106
107 * cpu
108   This key describes the CPU of the machine. You are advised, but not
109   restricted, to use one of the following strings:
110
111   - alpha
112   - DS80C390
113   - i386
114   - i486
115   - i586
116   - i686
117   - MIPS
118   - pa-risc
119   - ppc
120   - sparc
121   - sun4m
122   - sun4c
123   - sun4u
124   - VAX
125
126(For additions, email <ryan@wonko.com>)
127
128 * client
129   This is an optional string, no longer than 32 characters, the
130   describes the client. Usually it should be the client's name and
131   version number, and optionally the version number of the protocol
132   the client supports. Wonko's Uptime Client sends the string
133   WonkoClient/2.1.0.
134
135Return Values
136-------------
137Since UDP is a sessionless protocol, the server will not send a
138message back when you send a report. You'll just have to hope you got
139the data formatted right. In order to be at least a little helpful,
140I've added a field called "UDP Status" to the host details page of
141hosts that you own. Assuming you at least send the correct authkey,
142this field will be updated to contain the latest status or error
143message from the server.
144
145Faking
146------
147Now that you know the protocol, it's easy to write a client that fakes
148its uptime. Personally, I think hosts running FreeBSD 4.6.2 with
149uptimes over 3 years are pretty stupid. Maybe you think
150differently. In any case, hosts with fake uptimes will be marked bogus
151and ignored in the statistics, so there's really no point in wasting
152your time.
153
154
155Uptimes Protocol (rev. 5.0) - 09/09/2002, <ryan@wonko.com>
156
157Copyright � 2003 Ryan Grove. All rights reserved.
158