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