NAME

       xmlsysd  -  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

       xmlsysd [-v] [-d port] [-i port] [-n nconnect]

DESCRIPTION

       The xmlsysd 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.

       The maximum number of permitted forked daemons/connections can be set.  ([-n nconnect], default 10).  For
       xinetd-based  operation,  this  must  be  set  in /etc/xinetd.d/xmlsysd, as xinetd controls the number of
       permitted connections directly.

       The daemon can be invoked from a command line in verbose mode ([-v 1]) to obtain  debugging  information.
       Obviously  this  "breaks" the xml and hence the daemon!  The easiest way to debug is to invoke the daemon
       in inetd mode and verbose set so you can just interact with it on the command line.  Note that  verbosity
       can be set to certain values to "focus" on particular subroutines or operations and can be (re)set at the
       command line via the "verbose" command.

       Note that the port numbers used in the [-i port] or [-d port] arguments MUST match the port numbers  used
       by  the  client  applications.   In the case of at least the accompanying wulfstat application, the ports
       should default to 7887 in xinetd-based daemon and wulfstat and can be overridden in  the  latter  in  the
       hostfile.

SECURITY

       Security  methodology  and  requirements  vary from site to site, so it is not possible to "preconfigure"
       security for xmlsysd except in the context of a known  distribution  and  environment.   xmlsysd  has  no
       intrinsic  security  --  it will happily service connections from any host.  Although it was written with
       some care to avoid buffer overwrite attacks, it is impossible to guarantee that  this  care  was  totally
       successful.

       It  is  therefore  strongly  suggested that xmlsysd be secured unless it is run in a protected/firewalled
       environment.  In daemon mode, tcp wrappers together with  /etc/hosts.[allow,deny]  provide  a  reasonable
       layer  of security.  In xinetd-based operation (the installation default in the rpm) one will likely need
       to use (e.g.) ipchains or iptables, which  adds  kernel  overhead  but  allows  access  to  be  carefully
       controlled.   For the truly paranoid, although it hasn't been personally tested by me, there is no reason
       that one should not be able to use ssl (stunnel) or ssh  (port  forwarding)  to  bidirectionally  encrypt
       daemon traffic over even a WAN and simultaneously provide strong host identification.

       In  addition, unless one is either debugging or running a private forking daemon wrapped by e.g. ssh port
       forwarding, the daemon should generally be run as a non-privileged user such  as  "guest",  and  installs
       itself that way by default.

       NO  WARRANTY  is  provided  for  the  intrinsic security of this daemon, and it is best to assume that it
       contains an as-yet-undiscovered exploit in configuring your system to secure it. Use it at your own  risk
       and  take  whatever  measures  you  deem  necessary  to  make  that  level of risk acceptable in your own
       environment.

OPERATION AND API

       Once a connection is established the daemon accepts many commands:

       init

       Initialize all structures.  REQUIRED to be the first command.

       send Send the currently enabled node/clients statistics.

       sendall Send ALL available (not PID-based) node/client statistics.

       on flag1 flag2 flag3... (or) all off flag1 flag2 flag3... (or) all  Set  control  flags  that  mask  what
       information is sent by the send command.  The flags currently supported include:

       compress,  whitespace,  identity,  time,  users,  cpuinfo,  loadavg, meminfo, net, stat, sysvipc, uptime,
       version, pids, running, root.

       quit Terminates the connection -- the daemon instantiation dies.

       The data returned by the daemon in any non-verbose mode should be an http 1.1 header fragment followed by
       a  well-formed  xml  message  containing  the  encapsulated  statistics.  This message can be parsed with
       standard tools to extract the field contents for display or processing or recording.  Each  bottom  level
       statistic  should be tagged uniquely with at least an "id" identifier differentiating multiple interfaces
       or values with otherwise identical tags.

       When writing an interface, remember that the interface may well know (or need to know) only of  a  subset
       of the fields the daemon provides.  It should not "break" if it encounters unknown fields or if the field
       it expects is missing.  The xmlsysd is thus continue to be both scalable and  extensible  independent  of
       the tools that use it.

       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.

SUPPORTED STATISTICS

       The only reliable way to see if a statistic is supported is to crank it up and see what  it  finds.   You
       can  easily  do this in userspace -- just enter e.g. xmlsysd -i 7882 and the daemon will start up.  Enter
       "init".  You should see the all the non-pid fields.  Enter "on pids" and then "send".  You should see all
       the  supported statistics AND at least the status information a few "running" processes (repeat some more
       sends sends if necessary until you surprise something running).  Nothin' to it.

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 AND LICENSE INFO

       The author of xmlsysd is Robert G. Brown.  xmlsysd 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 at:

       http://www.phy.duke.edu/brahma

       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 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.