PROCD(8)

NAME
procstatd - provide anonymous information to enable the efficient remote monitoring of a network workstations, especially in the context of a beowulf or a LAN subnet.

SYNOPSIS
procstatd [-v] [-d port] [-i port]

DESCRIPTION
The procstatd daemon is designed to provide statistics and system information to hosts or monitor programs over the network via a simple, easily parsable API. In forking daemon mode ([-d port]) it listens upon the suggested port (which must be unoccupied) and, upon a connection request, accepts it and forks a copy of itself to handle the connection. The connection is not authenticated in any way, but should be safe and efficient on a protected cluster like a beowulf or firewall-protected LAN. In forking daemon mode only, the daemon can be invoked from a command line in verbose more ([-v]) to obtain debugging information. -v has no effect in inetd mode. In inetd mode ([-i port]) a suitable entry for procstatd must be made in /etc/services on an open port, e.g.:
procstatd    7885/tcp    # Private procstatd connection
and a suitable line added to /etc/inetd.conf:
procstatd    stream  tcp     nowait  nobody    /usr/sbin/tcpd    /usr/local/sbin/procstatd/procstatd -i 7885
The port 7885 used in this example is the default port accessed by the accompanying application "watchman". In this mode, tcp wrappers together with /etc/hosts.[allow,deny] provide a reasonable layer of security. In addition, the daemon should run just fine as a non-privileged user like guest. Finally, the daemon itself was written with some care to protect against buffer overwrite attacks. This mode of operation should thus be acceptable on ordinary clusters or LANs, and may be secure enough to permit remote monitoring of a LAN over an intermediary wide-area network.

OPERATION AND API
Once a connection is established the daemon accepts three commands:
   init Initializes all structures. REQUIRED to be the first command.
   send Triggers the sending of the node/clients statistics.
   quit Terminates the connection -- the daemon instantiation dies. It is anticipated that more commands will eventually be supported, but these three commands are likely to remain in place. After a send command is received, the daemon returns a message of the following general form over the interface: rgb=152.16.67.32 0.00|version=2.2.5-22 0.00|cpu 4.27|cpu_user 48.20|... The API is therefore a very simple one: Any supported statistic or systems datum that procstatd can find on the system and evaluate is appended to the string in an order determined by an enumerated list in the sources. If it isn't in the string, the system couldn't find it or evaluate it. Note that the daemon might well be run on many different system architectures with some different statistics on each, so this is a feature, not a bug! (Note: Need to collect field names of all current supported statistics in this man page -- in the meantime, it's probably easiest just to look at the output or read procstatd.h and the various statistics source modules, sorry.) Each entry consist of the statistic name, which may also be or include processed data separated by an "=", as in the system identity (first entry always) and the time and uptime fields. After a space, there is a %.2f number that may be raw data (load average) or a derived rate or statistic (eth0_rx). Finally the entry is terminated with a "|". To parse this is extremely simple. Fields are separated by |'s. Field names are separated from field data by a " ". Auxiliary data is separated from a field name by an "=". An interface to this daemon does not need to know which fields are available on any given host and can be easily written not to break if new fields are added or expected ones unavailable. The API is thus scalable and extensible independent of tools that use it, and both daemon and tools should be easily portable to a wide range of platforms or kernel revisions.

INSTALLATION
procstatd should be installed EITHER on a user-accessible path (for example, /usr/local/bin is good) OR on a root-accessible path in a place where public daemons are commonly kept (for example, /usr/local/sbin or /usr/local/etc). In the former case, procstatd can be invoked by users with no special privileges. See the notes on security, ownership and suid below. In the latter case, the daemon should be started up on boot via a fragment something like: if [ -x /usr/local/sbin/procstatd ] then
  /usr/local/bin/procstatd fi in rc.local or the equivalent on your system. See the notes on security, ownership and suid below. Be warned that watchman (the accompanying systems management UI) will be Unhappy if it doesn't find a procstatd to connect to and cannot automatically respawn one. This is alpha software, so the daemon might well crash from time to time!

RELIABILITY, SECURITY AND DEBUGGING
This is an ALPHA release of the daemon - it is not guaranteed to be stable. It was written reasonably carefully to be secure against buffer overwrite attacks and provides only but it cannot be guaranteed to be secure. There are several ways to make it adequately secure. The first is to run it as a forking daemon (-d mode) only in a protected beowulf or firewalled cluster, as this is a promiscuous mode primarily intended for debugging or (in a beowulf) the best performance. To use procstatd in an open LAN or cluster, use the inetd form, warp the owner of the daemon to nobody (as in the example above) and use hosts.allow to allow access only by those hosts permitted to access the daemon. Multicast mode (when it is supported) should automatically limit access to the information to the broadcast/multicast domain, but if the multicast is initiated via a command given via a daemon interface (as is one planned possibility) the same principles apply. In the event that procstatd bombs terribly it has a verbose mode that can be run if it is a forking daemon (and so has access to stderr) for debugging. To enable it use the -v flag:
   procstatd -v -d port_whatever Then telnet to the port:
   telnet procstatd_host port_whatever and enter
   init
   send
   send
   ...
   quit to see a trace of its activity. If you can't figure out what's wrong, send me a message and I'll try to help. As the software is alpha and I'm therefore presuming that you are a systems programmer, you might at least TRY to look at the code a bit (and add a few output statements and the like) to see where I screwed up first, but I'm easy either way. Additional suggestions, especially those accompanied by code or patches, are greatfully welcomed. Feel free to include patch authorship in comments within the patches -- they will be left in the source to immortalize your contributions. They'll also entitle you to tap into the "beverage" clause of the modified GPL but the other way... I'll buy you a beer.

FILES AND SEE ALSO
The binaries and scripts and public startup file are in (assuming you or your systems person installed them in /usr/local, of course):
  /usr/local/[bin,sbin]/procstatd There is additional documentation in the source package as well, mostly useful to developers. This product is, it should be emphasized, in ALPHA and is INTENDED to be modified and improved as it inches toward beta. There are probably other /proc files to monitor associated with particular networks or modules; it would be nice to add the 2.2.x network byte counts (instead of just the packet rates) for example. I'll put in a TODO list in the sources pretty soon.

REMARK
The procstatd/watchman source should also serve as a template that can be easily modified to support a variety of master/slave parallel computing paradigms. For example, the watchman UI could easily be hacked to split up certain chores into parallelized parts which could be sent to a collection of workstations via a modified "procstatd". The results could be sent back to and postprocessed by the modified watchman, and a new command sequence initiated. The package can in some sense be thought of as a template for a lightweight PVM-type parallel application. Think about it. Use it if you like, but UNDER THE MODIFIED GPL AS NOTED BELOW.

BUG REPORTS
Please send bug reports, patches, suggestions, etc. to rgb@phy.duke.edu. If the suggestions are sufficiently general, they may be worth discussing on the Beowulf or Extreme Linux lists, see
  http://www.beowulf.org
  http://www.extremelinux.org for information on what these projects are and instructions for joining in.

AUTHOR
The author of procstatd is Robert G. Brown. procstatd is provided under a slightly modified GPL version 2"b" (for beverage), see the README.GPL in the source. The current source is freely available from the author upon request (and is likely at http://www.phy.duke.edu/~rgb/procstatd.tar.gz). What's the GPL "b" modification? He's glad you asked. If you use the software and happen to meet the author (say, at a Linux Expo or the like) you are morally and ethically obligated to at least offer to buy him a beverage, if time and circumstances permit. If you are a software distributer/reseller (like Red Hat) and actually make money from the software, you might consider going a bit further and sending the author a bottle of nice, dry red wine from time to time as a "royalty". Thank you very much indeed.