Provided by: xymon-client_4.3.0~beta2.dfsg-9ubuntu1_i386 bug

NAME

       Xymon - introduction to Xymon

OVERVIEW

       Xymon is a tool for monitoring the health of your networked servers and
       the applications running on them.  It provides a simple, intuitive  way
       of  checking the health of your systems from a webbrowser, and can also
       alert you to any problems that arise through alarms sent as e-mail, SMS
       messages, via a pager or by other means.

       Xymon  is Open Source software, licensed under the GNU GPL.  This means
       that you are free to use Xymon as much as you like, and you are free to
       re-distribute it and change it to suit your specific needs. However, if
       you change it then you must make your changes available  to  others  on
       the same terms that you received Xymon originally. See the file COPYING
       in the Xymon source-archive for details.

       Xymon was called "Hobbit" until November 2008, when it was  renamed  to
       Xymon.  This  was  done  because the name "Hobbit" is trademarked.  The
       current release of Xymon is an  interim  version  without  all  of  the
       changes  needed  for  a  full  renaming, so there are still quite a few
       references to the old "hobbit" name.

       Xymon initially began life as an  enhancement  to  Big  Brother  called
       "bbgen".  Over a period of 5 years, Xymon has evolved from a small add-
       on to a full-fledged monitoring system with capabilities far  exceeding
       what was in the original Big Brother package. Xymon does still maintain
       some compatibility with Big Brother, so it is possible to migrate  from
       Big Brother to Xymon without too much trouble.

       Migrating  to  Xymon will give you a significant performance boost, and
       provide you with much more advanced monitoring.  The  Xymon  tools  are
       designed  for  installations  that  need  to  monitor a large number of
       hosts, with very little overhead on the monitoring server.   Monitoring
       of  thousands  of hosts with a single Xymon server is possible - it was
       developed to handle just this task.

FEATURES

       These are some of the core features in Xymon:

       Monitoring of hosts and networks
              Xymon collects information about your systems in two ways:  From
              querying  network  services (Web, LDAP, DNS, Mail etc.), or from
              scripts that run either on the Xymon server or  on  the  systems
              you monitor. The Xymon package includes a Xymon client which you
              can install on the servers you monitor; it collects  data  about
              the  CPU-load,  disk-  and memory-utilisation, logfiles, network
              ports in use, file- and directory-information and more.  All  of
              the  information  is  stored  inside  Xymon,  and you can define
              conditions that result in alerts,  e.g.  if  a  network  service
              stops responding, or a disk fills up.

       Centralized configuration
              All  configuration  of  Xymon  is done on the Xymon server. Even
              when monitoring hundreds or thousands of hosts, you can  control
              their  configuration centrally on the Xymon server - so there is
              no need for you to login to a system just to change  e.g.  which
              processes are monitored.

       Works on all major platforms
              The  Xymon  server  works  on  all  Unix-like systems, including
              Linux, Solaris, FreeBSD, AIX, HP-UX and others. The Xymon client
              supports  all  major  Unix  platforms,  and there are other Open
              Source projects - e.g. BBWin, see  http://bbwin.sourceforge.net/
              - providing support for Microsoft Windows based systems.

       A simple, intuitive web-based front-end
              "Green  is  good,  red  is  bad". Using the Xymon webpages is as
              simple as that. The hosts you monitor can be grouped together in
              a  way  that makes sense in your organisation and presented in a
              tree-structure.  The webpages  use  many  techniques  to  convey
              information  about  the  monitored systems, e.g. different icons
              can be used for recently changed statuses; links to subpages can
              be  listed  in multiple columns; different icons can be used for
              dialup-tests or reverse-tests; selected columns can  be  dropped
              or   unconditionally  included  on  the  webpages  to  eliminate
              unwanted information, or  always  include  certain  information;
              user-friendly  names  can be shown for hosts regardless of their
              true hostname. You can also  have  automatic  links  to  on-line
              documentation,  so  information  about  your critical systems is
              just a click away.

       Integrated trend analysis, historical data and SLA reporting
              Xymon   stores   trend-   and   availability-information   about
              everything  it  monitors.  So  if  you  need to look at how your
              systems behave over time, Xymon has all of the  information  you
              need:  Whether is is response times of your webpages during peak
              hours, the CPU utilisation over the past 4 weeks,  or  what  the
              availability  of a site was compared to the SLA - it's all there
              inside Xymon. All measurements are tracked and made available in
              time-based graphs.

              When  you  need  to  drill  down into events that have occurred,
              Xymon provides a powerful tool for viewing the event history for
              each  statuslog,  with  overviews of when problems have occurred
              during the past and easy-to-use zoom-in on the event.

              For SLA reporting, You can configure  planned  downtime,  agreed
              service  availability  level, service availability time and have
              Xymon generate availability reports directly showing the  actual
              availability  measured  against  the agreed SLA. Such reports of
              service  availability  can  be  generated  on-the-fly,  or  pre-
              generated e.g. for monthly reporting.

       Role-based views
              You  can  have  multiple  different  views of the same hosts for
              different parts of the  organisation,  e.g.  one  view  for  the
              hardware  group,  and  another  view for the webmasters - all of
              them fed by the same test tools.

              If you have a  dedicated  Network  Operations  Centre,  you  can
              configure precisely which alerts will appear on their monitors -
              e.g. a simple anomaly in the system logfile need not  trigger  a
              call  to 3rd-level support at 2 AM, but if the on-line shop goes
              down you do want someone to respond immediately.  So you put the
              webcheck for the on-line shop on the NOC monitor page, and leave
              out the log-file check.

       Also for the techies
              The Xymon user-interface is simple, but engineers will also find
              lots  of relevant information. E.g. the data that clients report
              to Xymon  contain  the  raw  output  from  a  number  of  system
              commands.   That  information is available directly in Xymon, so
              an administrator no longer needs to login to a server to get  an
              overview  of  how  it is behaving - the very commands they would
              normally run have alredy been performed, and the results are on-
              line in Xymon.

       Easy to adapt to your needs
              Xymon  includes  a  lot  of tests in the core package, but there
              will always be something specific to your setup that  you  would
              like  to  watch.  Xymon allows you to write test scripts in your
              favourite scripting language and have the  results  show  up  as
              regular  status  columns  in  Xymon. You can trigger alerts from
              these, and  even  track  trends  in  graphs  just  by  a  simple
              configuration setting.

       Real network service tests
              The  network  test  tool  knows  how  to test most commonly used
              protocols, including HTTP, SMTP (e-mail), DNS,  LDAP  (directory
              services), and many more. When checking websites, it is possible
              to not only check that the webserver  is  responding,  but  also
              that the response looks correct by matching the response against
              a pre-defined pattern or a checksum. So  you  can  test  that  a
              network  service  is  really  working and supplying the data you
              expect - not just that the service is running.

              Protocols that use SSL encryption  such  as  https-websites  are
              fully  supported,  and  while checking such services the network
              tester will automatically run a check of the validity of the SSL
              server  certificate,  and warn about certificates that are about
              to expire.

       Highly configurable alerts
              You want to know when something breaks. But you  don't  want  to
              get  flooded  with  alerts  all  the time. Xymon lets you define
              several criteria for when to send out an alert, so you only  get
              alerts  when there is really something that needs your attention
              right away. While you are handling an  incident,  you  can  tell
              Xymon  about  it  so  it  stops sending more alerts, and so that
              everyone else can check with Xymon and know that the problem  is
              being taken care of.

       Combined super-tests and test interdependencies
              If a single test is not enough, combination tests can be defined
              that combine the result of several tests  to  a  single  status-
              report.   So  if  you  need  to monitor that at least 3 out of 5
              servers are running at any time, Xymon can do that for  you  and
              generate the necessary availability report.

              Tests  can  also  be configured to depend on each other, so that
              when a critical router goes down you will get  alerts  only  for
              the router - and not from the 200 hosts behind the router.

SECURITY

       All  of  the Xymon server tools run under an unprivileged user account.
       A single program - the hobbitping(1) network connectivity tester - must
       be  installed  setuid-root,  but  has been written so that it drops all
       root  privileges  immediately  after  performing  the  operation   that
       requires root privileges.

       It is recommended that you setup a dedicated account for Xymon.

       Communications  between  the Xymon server and Xymon clients use the Big
       Brother TCP port  1984.  If  the  Xymon  server  is  located  behind  a
       firewall,  it must allow for inbound connections to the Xymon server on
       tcp port 1984. Normally, Xymon clients  -  i.e.  the  servers  you  are
       monitoring  -  must be permitted to connect to the Xymon server on this
       port. However, if that is not possible due to firewall  policies,  then
       Xymon includes the hobbitfetch(8) and msgcache(8) tools to allows for a
       pull-style way of collecting data, where it is the  Xymon  server  that
       initiates connections to the clients.

       The Xymon webpages are dynamically generated through CGI programs.

       Access  to  the  Xymon  webpages  is  controlled through your webserver
       access controls, e.g. you can require a login through some form of HTTP
       authentication.

DEMONSTRATION SITE

       A site running this software can be seen at http://www.hswn.dk/hobbit/

PREREQUISITES AND INSTALLATION

       You  will need a Unix-like system (Linux, Solaris, HP-UX, AIX, FreeBSD,
       Mac OS X or similar) with a webserver installed. You will also need a C
       compiler  and  som additional libraries, but many systems come with the
       required development tools and libraries  pre-installed.  The  required
       libraries are:

       RRDtool  This  library  is  used to store and present trend-data. It is
       required.

       libpcre This library is used  for  advanced  pattern-matching  of  text
       strings in configuration files. This library is required.

       OpenSSL This library is used for communication with SSL-enabled network
       services.  Although optional, it is recommended that you  install  this
       for Xymon since many network tests do use SSL.

       OpenLDAP  This library is used for testing LDAP servers. Use of this is
       optional.

       For more detailed information about Xymon system requirements  and  how
       to  install Xymon, refer to the online documentation "Installing Xymon"
       available from the Xymon webserver (via the "Help" menu), or  from  the
       "docs/install.html" file in the Xymon source archive.

SUPPORT and MAILING LISTS

       hobbit@hswn.dk is an open mailing list for discussions about Xymon.  If
       you  would  like  to   participate,   send   an   e-mail   to   hobbit-
       subscribe@hswn.dk to join the list.

       An     archive    of    the    mailing    list    is    available    at
       http://www.hswn.dk/hobbiton/

       If you just want to be  notified  of  new  releases  of  Xymon,  please
       subscribe  to  the  hobbit-announce  mailing  list. This is a moderated
       list, used only for announcing new Xymon releases. To be added  to  the
       list, send an e-mail to hobbit-announce-subscribe@hswn.dk.

XYMON SERVER TOOLS

       These tools implement the core functionality of the Xymon server:

       hobbitd(8)  is  the  core  daemon  that  collects all reports about the
       status of your hosts. It uses a number of helper modules  to  implement
       certain  tasks  such  as  updating  logfiles  and  sending  out alerts:
       hobbitd_client, hobbitd_history, hobbitd_alert and  hobbitd_rrd.  There
       is also a hobbitd_filestore module for compatibility with Big Brother.

       hobbitd_channel(8)  Implements  the  communication  between  the  Xymon
       daemon and the other Xymon server modules.

       hobbitd_history(8) Stores historical data about the things  that  Xymon
       monitors.

       hobbitd_rrd(8)  Stores  trend data, which is used to generate graphs of
       the data monitored by Xymon.

       hobbitd_alert(8) handles alerts. When a status changes  to  a  critical
       state, this module decides if an alert should be sent out, and to whom.

       hobbitd_client(8) handles data collected by the Xymon clients, analyzes
       the data and feeds back several status updates to Xymon  to  build  the
       view of the client status.

       hobbitd_hostdata(8)   stores  historical  client  data  when  something
       breaks. E.g. when a webpage stops responding hobbitd_hostdata will save
       the  latest client data, so that you can use this to view a snapshot of
       how the system state was just prior to it failing.

XYMON NETWORK TEST TOOLS

       These tools are used on servers that execute tests of network services.

       hobbitping(1) performs network connectivity (ping) tests.

       bbtest-net(1) runs the network service tests.

       bbretest-net.sh(1) is an extension script for re-doing  failed  network
       tests  with  a  higher  frequency  than  the normal network tests. This
       allows Xymon to pick up the recovery of a network service as soon as it
       happens, resulting in less downtime being recorded.

XYMON TOOLS HANDLING THE WEB USER-INTERFACE

       These tools take care of generating and updating the various Xymon web-
       pages.

       bbgen(1) takes care of updating the Xymon webpages.

       hobbitsvc.cgi(1) This CGI program generates an HTML view  of  a  single
       status log.  It is used to present the Xymon status-logs.

       hobbitgraph.cgi(1)  This CGI program generates graphs of the trend-data
       collected by Xymon.

       hobbit-hostgraphs.cgi(1) When you want to combine multiple graphs  into
       one,  this CGI lets you combine graphs so you can e.g. compare the load
       on all of the nodes in your server farm.

       hobbit-nkview.cgi(1) Generates the Critical Systems view, based on  the
       currently  critical  systems  and the configuration of what systems and
       services you want to monitor when.

       bb-hist.cgi(1) This CGI program  generates  a  webpage  with  the  most
       recent history of a particular host+service combination.

       bb-eventlog.cgi(1)  This  CGI  lets  you view a log of events that have
       happened over a period of time, for a  single  host  or  test,  or  for
       multiple systems.

       bb-ack.cgi(1) This CGI program allows a user to acknowledge an alert he
       received from  Xymon  about  a  host  that  is  in  a  critical  state.
       Acknowledging an alert serves two purposes: First, it stops more alerts
       from being sent so the technicians are not bothered  wit  more  alerts,
       and  secondly  it  provides  feedback  to  those  looking  at the Xymon
       webpages that the problem is being handled.

       hobbit-mailack(8) is a tool for processing acknowledgements sent via e-
       mail, e.g. as a response to an e-mail alert.

       hobbit-enadis.cgi(8)  is a CGI program to disable or re-enable hosts or
       individual tests.  When disabling a host or test, you stop alarms  from
       being  sent and also any outages do not affect the SLA calculations. So
       this  tool  is  useful  when  systems  are  being  brought   down   for
       maintenance.

       bb-findhost.cgi(1)  is  a  CGI  program  that finds a given host in the
       Xymon webpages.  As  your  Xymon  installation  grows,  it  can  become
       difficult  to remember exactly which page a host is on; this CGI script
       lets you find hosts easily.

       bb-rep.cgi(1)  This  CGI  program  triggers  the  generation  of  Xymon
       availability reports, using bbgen(1) as the reporting back-end engine.

       bb-replog.cgi(1)  This  CGI program generates the detailed availability
       report for a particular host+service combination.

       bb-snapshot.cgi(1) is a CGI program to build the Xymon  webpages  in  a
       "snapshot" mode, showing the look of the webpages at a particular point
       in time. It uses bbgen(1) as the back-end engine.

       hobbit-statusreport.cgi(1) is a CGI program reporting test results  for
       a single status but for several hosts. It is used to e.g. see which SSL
       certificates are about to expire, across all of the Xymon webpages.

       bb-csvinfo.cgi(1) is a CGI program to present information about a host.
       The  information  is  pulled  from a CSV (Comma Separated Values) file,
       which is easily exported from any spreadsheet or database program.

CLIENT-SIDE TOOLS

       logfetch(1) is a utility used by  the  Xymon  Unix  client  to  collect
       information  from  logfiles  on the client. It can also monitor various
       other file-related data, e.g. file metadata or directory sizes.

       clientupdate(1) Is used on Xymon clients, to automatically  update  the
       client  software  with  new versions. Through this tool, updates of the
       client software can happen without an administrator having to logon  to
       the server.

       msgcache(8)  This  tool  acts  as a mini Xymon server to the client. It
       stores client data internally, so that the hobbitfetch(8)  utility  can
       pick  it up later and send it to the Xymon server. It is typically used
       on hosts that cannot contact the Xymon server directly due to  network-
       or firewall-restrictions.

XYMON COMMUNICATION TOOLS

       These  tools  are  used for communications between the Xymon server and
       the Xymon clients. If there are no firewalls then they are not  needed,
       but  it  may be necessary due to network or firewall issues to make use
       of them.

       bbproxy(8) is a  proxy-server  that  forwards  Xymon  messages  between
       clients  and  the Xymon server. The clients must be able to talk to the
       proxy, and the proxy must be able to talk to the Xymon server.

       hobbitfetch(8) is used when the client is not  able  to  make  outbound
       connections  to  neither  bbproxy  nor the Xymon server (typically, for
       clients located in a DMZ network zone). Together with  the  msgcache(8)
       utility running on the client, the Xymon server can contact the clients
       and pick up their data.

OTHER TOOLS

       hobbitlaunch(8) is a program scheduler for Xymon. It acts as  a  master
       program  for  running  all of the Xymon tools on a system. On the Xymon
       server, it controls running all of the server tasks. On a Xymon client,
       it  periodically  launches  the client to collect data and send them to
       the Xymon server.

       bb(1) is the tool used to communicate with the  Xymon  server.   It  is
       used  to  send  status  reports to the Xymon server, through the custom
       Xymon/BB protocol, or via HTTP. It can be used to query  the  state  of
       tests  on  the  central  Xymon  server and retrieve Xymon configuration
       files. The server-side script bbmessage.cgi(1) used to receive messages
       sent via HTTP is also included.

       bbcmd(1)  is  a  wrapper for the other Xymon tools which sets up all of
       the environment variables used by Xymon tools.

       bbhostgrep(1) is a utility for  use  by  Xymon  extension  scripts.  It
       allows  an  extension  script  to  easily  pick  out the hosts that are
       relevant to a script, so it need not parse a huge  bb-hosts  file  with
       lots of unwanted test-specifications.

       bbhostshow(1)  is a utility to dump the full bb-hosts(5) file following
       any "include" statements.

       bbdigest(1) is a utility to compute message digest values  for  use  in
       content checks that use digests.

       bbcombotest(1)  is  an  extension script for the Xymon server, allowing
       you to build complicated tests from simpler Xymon  test  results.  E.g.
       you  can  define  a  test  that  uses  the  results  from  testing your
       webserver, database server and router to have a single test showing the
       availability of your enterprise web application.

       trimhistory(8) is a tool to trim the Xymon history logs. It will remove
       all log entries and optionally  also  the  individual  status-logs  for
       events that happened before a given time.

VERSIONS

       Version  1  of  bbgen  was  relased in November 2002, and optimized the
       webpage generation on Big Brother servers.

       Version 2 of bbgen was released in April 2003, and  added  a  tool  for
       performing network tests.

       Version  3  of bbgen was released in September 2004, and eliminated the
       use of several external libraries for network  tests,  resulting  in  a
       significant performance improvement.

       With  version 4.0 released on March 30 2005, the project was de-coupled
       from Big Brother, and the name changed to Xymon. This version  was  the
       first  full  implementation  of the Xymon server, but it still used the
       data collected by Big Brother clients for monitoring host metrics.

       Version 4.1 was released in July 2005 included a  simple  Xymon  client
       for Unix. Logfile monitoring was not implemented.

       Version  4.2 was released in July 2006, and includes a fully functional
       Xymon client for Unix.

COPYRIGHT

       Xymon is
         Copyright (C) 2002-2009 Henrik Storner <henrik@storner.dk>
       Parts of the Xymon sources  are  from  public-domain  or  other  freely
       available sources. These are the the Red-Black tree implementation, and
       the MD5-, SHA1- and RIPEMD160-implementations. Details of  the  license
       for  these  is in the README file included with the Xymon sources.  All
       other files are released under the GNU General Public  License  version
       2,  with the additional exemption that compiling, linking, and/or using
       OpenSSL is allowed.  See the file COPYING for details.

SEE ALSO

       hobbitd(8),  hobbitd_channel(8),  hobbitd_history(8),   hobbitd_rrd(8),
       hobbitd_alert(8),        hobbitd_client(8),        hobbitd_hostdata(8),
       hobbitping(1),     bbtest-net(1),     bbretest-net.sh(1),     bbgen(1),
       hobbitsvc.cgi(1), hobbitgraph.cgi(1), hobbit-hostgraphs.cgi(1), hobbit-
       nkview.cgi(1),   bb-hist.cgi(1),   bb-eventlog.cgi(1),   bb-ack.cgi(1),
       hobbit-mailack(8),    hobbit-enadis.cgi(8),   bb-findhost.cgi(1),   bb-
       rep.cgi(1),     bb-replog.cgi(1),      bb-snapshot.cgi(1),      hobbit-
       statusreport.cgi(1),  bb-csvinfo.cgi(1),  logfetch(1), clientupdate(1),
       msgcache(8),  bbproxy(8),   hobbitfetch(8),   hobbitlaunch(8),   bb(1),
       bbmessage.cgi(1),  bbcmd(1), bbhostgrep(1), bbhostshow(1), bbdigest(1),
       bbcombotest(1),   trimhistory(8),   bb-hosts(5),   hobbitlaunch.cfg(5),
       hobbitserver.cfg(5),    hobbit-alerts.cfg(5),    hobbit-clients.cfg(5),
       client-local.cfg(5)