|
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 here.
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.noctumdesign.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, noctumdesign's Uptime Client might send the following string:
51cbb9711de405x06a877z75404be027|415|100.00|0|Windows|2000|i686|noctumdesignClient/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|noctumdesignClient/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.
- AIX
- BeOS
- BSDi
- Darwin
- Embedded
- FreeBSD
- HPLaser
- HPUX
- IRIX
- IRIX64
- Linux
- MacOS
- NetBSD
- Netware
- OpenBSD
- OpenVMS
- QNX
- RiscRouter
- SunOS
- TINI OS
- Ultrix
- Unixware
- Windows
(For additions, email greatbotboy@noctumdesign.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:
- alpha
- DS80C390
- i386
- i486
- i586
- i686
- MIPS
- pa-risc
- ppc
- sparc
- sun4m
- sun4c
- sun4u
- VAX
(For additions, email greatbotboy@noctumdesign.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. noctumdesign's Uptime Client
sends the string noctumdesignClient/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 "UDP Status" 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 Protocol (rev. 5.0) - 09/09/2002, greatbotboy@noctumdesign.com
|