XYMON(7)						 Miscellaneous Information Manual						  XYMON(7)

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  oth-
       ers 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 refer-
       ences 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  sup-
	      port 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 mul-
	      tiple 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 util-
	      isation  over  the  past 4 weeks, or what the availability of a site was compared to the SLA - it's all there inside Xymon. All mea-
	      surements 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  nec-
	      essary 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  fire-
       wall,  it must allow for inbound connections to the Xymon server on tcp port 1984. Normally, Xymon clients - i.e. the servers you are moni-
       toring - 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-sub-
       scribe@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 mul-
       tiple 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  diffi-
       cult 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 net-
       work- 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), hobbit-
       ping(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), trimhis-
       tory(8), bb-hosts(5), hobbitlaunch.cfg(5), hobbitserver.cfg(5), hobbit-alerts.cfg(5), hobbit-clients.cfg(5), client-local.cfg(5)

Xymon							    Version 4.2.3:  4 Feb 2009							  XYMON(7)