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.