NAME

upclient —

logs system uptime with uptimes.hostingwired.com.

SYNOPSIS

[sudo] upclient [-h] [-V] [-v|-vv|-vvv]

[sudo] kill `cat /var/run/upclient.pid`

DESCRIPTION

Client for The Uptimes Project

The Uptimes Project collects data on the amount of time a computer has been running since its last reboot and provides statistics on various operating system and hardware configurations.

Upon starting, the daemon logs a brief message to stderr and syslog (on those operating systems that support syslog) then forks into the background. If the daemon cannot start it will try to output error messages to stderr and syslog. Normally the daemon runs quietly and unobtrusively in the background.

OPTIONS

By default no uptime transmissions will be logged. This means that once UpClient has started, there will be no indication in the system logs that UpClient is still running unless it encounters a problem.

-v: Every few minutes whenever UpClient transmits data to the server an entry will be recorded to syslog. This is useful for monitoring whether UpClient is working.
-vv: Verbose-verbose mode. A few additional status and error messages will be logged to aid basic troubleshooting.
-vvv: Verbose-verbose-verbose mode may be useful for troubleshooting or to satisfy curiosity. To see even more status messages, UpClient can be compiled in DEBUG mode (see below).
-h: Display a brief usage message and exit.
-V: Show the version and exit.

If you need to stop UpClient, signal it with TERM and it will clean up its pid file then quit. The easiest way to do this is [sudo] kill `cat /var/run/upclient.pid`. The daemon ignores INT signals.

GETTING STARTED

1. Create an account at: http://uptimes.hostingwired.com/.
2. Add a host, this gives you an authorization key.
3. Paste your auth key into /usr/local/etc/upclient.conf.
4. Start the upclient daemon: [sudo] /usr/local/sbin/upclient.
5. Visit your account at http://uptimes.hostingwired.com/ to view your
machine's status and other collected statistics.

CONTROLLING UPCLIENT

UpClient performs certain actions when it receives certain signals:

SIGALRM: Resets the timer and causes UpClient to transmit uptime status immediately.
SIGHUP: Tells UpClient to re-read the configuration file and restart.

TROUBLESHOOTING

If you suspect a problem with UpClient, check your syslog for upclient messages.

My AuthKey is correct but UpClient refuses to start due to 'ERROR: AuthKey is not 32 bytes long!'".

Remove any enclosing braces < > from the authkey. As of 5.0b7 these have been removed from the upclient.conf template to avoid confusion.

The uptime server is not receiving any reports. Everything appears fine and my machine is not behind a firewall."

Make sure the client is not compiled with -DPARANOID. This flag is for debugging only, it prevents any reports from actually being transmitted.

On BSD systems UpClient must be run as root to send usage and idle time. As of UpClient 5.0b6, Darwin / Mac OS X no longer has this requirement as new code was added for Mach-based systems where this restriction does not apply.

Use the following command to trigger an immediate UpClient transmission:

[sudo] kill -SIGALRM `cat /var/run/upclient.pid`

To have UpClient output many debugging messages to the syslog, recompile it in debug mode. Set the EXTRA_CFLAGS envvar to '-DDEBUG', or edit the Makefile to add '-DDEBUG' to the CFLAGS line in the section appropriate for your system, like this:

CFLAGS='-DDEBUG' \

FILES

/usr/local/sbin/upclient: client
/usr/local/etc/upclient.conf: configuration
/var/run/upclient.pid: process id
/usr/local/share/doc/upclient/: documentation

AUTHORS

Carsten Klapp <carstenklapp@users.sourceforge.net>
Protocol 5 client

Ryan Grove <ryan@wonko.com>
Protocol 5, Uptimes Server and web site

Alex C. de Haas <alex@uptimes.net>
Protocol 4 client

Martijn Broenland <tgm@uptimes.net>
Original Author

Many people have contributed to the uptime client. Please see /usr/local/share/doc/upclient/AUTHORS.

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

BUGS

IMPORTANT: 5.0b8 includes bug fixes to prevent potential buffer overflows which could present a local root compromise on BSD-based systems including Mac OS X. All upclient 5 beta users should upgrade to 5.0b8 as soon as possible.

WARNING: There are potential security issues under Linux (strcpy in stats-lns.c). For now this isn't a critical issue as upclient does not require superuser priveleges to run under Linux. This will be fixed in the next beta.

When /usr/local/etc/upclient.conf cannot be found at the compiled-in path, UpClient tries to find one in a couple other locations, and logs which one is being used instead. If there are errors in the "alternate" config file, UpClient will mention the name and path of the compiled-in config file instead of the one found.

HISTORY

Version 5 by default transmits uptime information via UDP to port 49153 to reduce load on the server. If you are behind a closed firewall or using a proxy server the client uses the older protocol 4.2 via HTTP instead, with the same functionality. See /usr/local/share/doc/upclient/ for more information.

$Id: upclient.man,v 1.9 2003/05/26 21:35:19 carstenklapp Exp $