NAME
libwulf - xmlsysd client library
SYNOPSIS
libwulf.a
DESCRIPTION
libwulf.a is the core common library required by wulfstat and
wulflogger, two xmlsysd clients that poll and display various
statistics from a cluster in a user-controllable loop. libwulf
contains routines that open and parse a wulfhosts (cluster/lan
descriptor) file, establish xmlsysd connections in a threaded subtask
to all hosts in the wulfhosts file, and in parallel with this
initialize and update selected statistics. libwulf functions form an
API adequate to support many kinds of toplevel log and gui applications
reasonably efficiently.
The best way to develop an application using libwulf is to examine one
of the existing applications such as wulflogger. The steps are roughly
as follows:
* Initialize libxml
* Allocate various linked lists using the provided linked list
routines
* Read and parse the wulfhosts file
* Set the dctl (display control) state for all hosts. This struct
MUST correspond to the state of the xmlsysd on the hosts.
* Connect to all hosts, generally in a threaded loop that runs in
parallel with any display process (so that if a host goes down the
display task does not block).
* Initialize all host-derived values from an initial xmlsysd return
* Enter a polling work loop that sends all hosts the "send" commmand,
updates all host derived values and then sleeps. This loop can contain
branches that alter dctl state, alter the display, or do pretty much
whatever you want with the data retrieved.
* Display or otherwise utilize the per-host data.
* Exit (cleanly or otherwise) on request.
DCTL FLAGS
The following is the dctl struct currently used by libwulf. The
contents are all flags that can take on values of 0 (no or false) or
not-zero (yes or true). There is a fairly straightforward
correspondance between dctl state flags and throttleable xmlsysd tags
and their (possibly sub-tagged) contents.
typedef struct {
int compress; /* Do we compress xml output? */
int whitespace; /* Do we squeeze out whitespace? */
/*
* All the following toggle various components of the return. Some
of
* these are only needed "once" in a typical monitoring session
anyway
* and can be pulled from the init return (which always sends
* "everything"). Future developers should note the 1:1
correspondance
* between many of these flags and "init_XXXX.c" and "update_XXXX.c"
* sources and calls.
*/
/* system call stuff */
int identity; /* Do we update system identity? */
int time; /* Do we update system time? */
int users; /* Do we update system pids? */
/* proc-derived stuff */
int cpuinfo; /* Do we update proc cpuinfo? */
int loadavg; /* Do we update proc loadavg? */
int meminfo; /* Do we update proc meminfo? */
int net; /* Do we update proc net? */
int stat; /* Do we update proc stat? */
int sysvipc; /* Do we update proc shared memory stuff? */
int uptime; /* Do we update proc uptime? */
int version; /* Do we update proc (kernel) version? */
/* Processes (in /proc/XXXXX where XXXXX is a pid) */
int pids; /* Do we update pids at all? */
int running; /* Running PIDs or all? */
int root; /* Including those owned by root? */
List *userlist; /* A linked list of usernames to watch */
List *tasklist; /* A linked list of tasknames to watch */
} Dctl;
SEE ALSO:
wulfstat(1), wulflogger(1)
PUBLICATION RULES
libwulf.a can be modified and used at will by any user, provided that:
a) The original copyright notices are maintained and that the source,
including all modifications, is made publically available at the time
of any derived publication. This is open source software according to
the precepts and spirit of the Gnu Public License. See the
accompanying file COPYING, which also must accompany any
redistribution.
b) The author of the code (Robert G. Brown) is appropriately
acknowledged and referenced in any derived use or publication.
c) Full responsibility for the accuracy, suitability, and
effectiveness of the program rests with the users and/or modifiers. As
is clearly stated in the accompanying copyright.h:
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ACKNOWLEDGEMENTS
None to speak of now, but a good place to comply with b) above later,
if you hack this code. Well, I should probably acknowledge the
essential help of Icon (Konstantin Raibetsev) and Seth Vidal, the
entire beowulf list, and various books on xml, network programming
(e.g. Stevens) and a cast of thousands. So let’s assume that I just
did;-)
GPL 2b; see the file COPYING that accompanies the source of this
program. This is the "standard Gnu General Public License version 2 or
any later version", with the one minor (humorous) "Beverage"
modification listed below. Note that this modification is probably not
legally defensible and can be followed really pretty much according to
the honor rule.
As to my personal preferences in beverages, red wine is great, beer is
delightful, and Coca Cola or coffee or tea or even milk acceptable to
those who for religious or personal reasons wish to avoid stressing my
liver.
The Beverage Modification to the GPL:
Any satisfied user of this software shall, upon meeting the primary
author(s) of this software for the first time under the appropriate
circumstances, offer to buy him or her or them a beverage. This
beverage may or may not be alcoholic, depending on the personal ethical
and moral views of the offerer. The beverage cost need not exceed one
U.S. dollar (although it certainly may at the whim of the offerer:-)
and may be accepted or declined with no further obligation on the part
of the offerer. It is not necessary to repeat the offer after the
first meeting, but it can’t hurt...