README file for Xymon
=====================

What is it ?
------------
Xymon is a system for monitoring your network servers and
applications. It is heavily inspired by the Big Brother
tool, but is a complete re-implementation with a lot of added
functionality and performance improvements. A slightly more
detailed rationale for Xymon is in the docs/about.html file.

NOTE: On Nov 10 2008, Hobbit was officially renamed to
"Xymon". The name "Hobbit" is trademarked, and therefore
cannot be used without permission from the trademark
holders.


How to install
--------------
Detailed installation instructions are in the
docs/install.html file. Essentially, it boils down
to running
	./configure
	make
	make install
but do have a look at the install.html file for more
detailed instructions.


Documentation
-------------
The docs/ directory holds information about the basic
installation and configuration of Xymon. All of the
tools and configuration files in Xymon have man-pages
that are installed automatically when installing Xymon.
The xymon(7) man page provides an introduction to
Xymon and has pointers to the other man-pages of the
package.


License
-------
Xymon is copyrighted (C) 2002-2017 by Henrik Storner.

Xymon is Open Source software, made available under the
GNU General Public License (GPL) version 2, with the explicit
exemption that linking with the OpenSSL libraries is permitted.
See the file COPYING for details.

Xymon is released under the GPL, and therefore available
free of charge. However, if you find it useful and want
to encourage further development, I do have an Amazon
wishlist at http://www.amazon.co.uk/ - just search for
my mail-address (henrik@hswn.dk). A contribution in the
form of a book, CD or DVD is appreciated.

The following files are distributed with Xymon and used
by Xymon, but written by others and are NOT licensed under the GPL:

* The lib/rmd160c.c, lib/rmdconst.h, lib/rmdlocl.h and lib/ripemd.h
  files are Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com).
  The license is BSD-like, but see these files for the exact license.
  The version in Xymon was taken from the FreeBSD CVS archive.

* The lib/md5.c and lib/md5.h files are (C) L. Peter Deutsch,
  available under a BSD-like license from
  http://sourceforge.net/projects/libmd5-rfc/

* The lib/sha1.c file is originally written by by Steve Reid
  <steve@edmweb.com> and placed in the public domain. The version
  in Xymon was taken from the "mutt" mail client sources, so
  some changes were done by Thomas Roessler <roessler@does-not-exist.org>.


Support
-------
There is an open mailing list for discussing Xymon, asking
questions about how to use Xymon, reporting bugs etc. You
can subscribe to the list by sending an e-mail to

   xymon-subscribe@xymon.com

or on the web http://lists.xymon.com/mailman/listinfo/xymon

Please note that mail sent from addresses that are not subscribed
to the list need to go through a moderator approval, and therefore
may not show up on the list for some time.

Unix client for Xymon
======================
As of version 4.1, Xymon ships with a native client for
most Unix-based systems.

The Xymon client will generate status columns for:
* cpu    : CPU utilisation
* disk   : Filesystem (disk) utilisation
* files  : File- and directory attributes and sizes
* memory : Memory and Swap utilisation
* msgs   : Log file messages
* ports  : TCP/IP Network connections
* procs  : Processes

It will also feed data to generate some graphs:
* ifstat : Raw traffic data for network interfaces
* netstat: TCP/IP statistics
* vmstat : Various performance counters (OS-specific)

In the default setup, all configuration of disk thresholds,
load limits, which processes to monitor etc. is done on the
Xymon server, NOT on the client. This is to allow centralized
configuration of the monitored systems.

If you prefer to have the client configuration done locally
on each of the systems you monitor, this is an option when
building the client. It is possible to have a mix of systems,
with some systems configured locally, and others that use
the central configuration. Note: The locally-configured
client requires the PCRE libraries to be installed on the
client host.

The Xymon client is released under the GNU GPL, version 2
or later. See the file COPYING for details.


Installation
============
Building the client package requires a working C compiler
and GNU make on the target platform. None of the extra libraries
needed for building Xymon are used by the client - so a
plain C compiler installation with GNU make is all that is
needed.

To build the client:

	- create a "xymon" userid on the system
	  (not required, but recommended).
	- extract the Xymon source archive
	- cd to the xymon-X.X directory
	- run "./configure --client; make"
	- as root, run "make install"

The client installation is kept entirely within
the "xymon" users' home-directory. All client-related
files are in the ~xymon/client/ directory. If convenient,
this directory can be copied directly to other systems
of the same type, so you need not build the client from
source on all systems.


Running it
==========
To start the client, su to the "xymon" user, then run
   $HOME/client/runclient.sh start

You should arrange for your boot-time scripts to run this
command at startup.


Client configuration
====================
All of the normal configuration is done on the Xymon SERVER.
See the analysis.cfg(5) and client-local.cfg(5) man-
pages on the Xymon server.


Hostname detection
------------------
The client reports to Xymon using the hostname taken from
the "uname -n" command output. Whether this provides a fully
qualified DNS name (myserver.foo.com) or a simple hostname
(myserver) varies a lot. If your client gets it wrong, you
can override the default with the "--hostname=CLIENT.HOST.NAME"
option to the runclient.sh startup command.


OS detection on Linux systems
-----------------------------
The client normally determines the operating system auto-
matically from the "uname -s" output. This results in all
Linux systems reporting as "Linux" - which causes the
vmstat graphs to fail for certain types of systems:

	- Systems running Linux kernels 2.2.x (e.g. Debian Woody)
	  Must report "linux22" instead.
	- Red Hat Enterprise Linux 2.1
	  Must report "linux22" instead.
	- Red Hat Enterprise Linux 3 update 1
	  The default is adequate
	- Red Hat Enterprise Linux 3 update 2 or later
	  Must report "rhel3" instead.
	- Red Hat Enterprise Linux 4 update 2 and later
	  The default is adequate

To override the default, start the client using the
"--os=OSNAME" option to the runclient.sh startup command.

(Thanks to Thomas Seglard Enata for providing the about the
 various Red Hat versions).


Extension scripts
-----------------
The file client/etc/clientlaunch.cfg configures the "xymonlaunch"
used to run the client scripts. If you need to run extension
scripts for your client, you can add them to this file. The
environment variables commonly used by Big Brother-based extensions
are made available by xymonlaunch for the scripts, so in most
cases extensions written for the Big Brother client will work
without modifications on Xymon.

Each script should have a separate section in the file, like the
default one that runs the core client:

[myextension]
	ENVFILE /usr/lib/xymon/client/etc/xymonclient.cfg
	CMD /usr/lib/xymon/client/ext/myscript.sh
	INTERVAL 5m
	LOGFILE /usr/lib/xymon/client/logs/myscript.log

See the tasks.cfg(5) man-page for a full description
of this file.


Installing on multiple systems
==============================
After building and installing the client on one system, you can
copy the client installation to other systems. You need only copy
the directory structure with the "client" directory.

The client does not have any hardcoded file- or directory-paths
embedded in it, so you can put the client files anywhere you
like, as long as you preserve the directory structure below the
"client" directory.



Henrik Stoerner, 2006-Apr-23

Enabling the "backfeed" channel on the Xymon server
===================================================

Background
----------
Traditionally, all communication between modules on the
Xymon server uses a TCP connection to xymond. This is a
simple standardized way of talking to the daemon, e.g. to
send status updates from xymond_client or xymonnet into
the xymond daemon.

However, a TCP connection also carries quite a bit of overhead.
On a server with a very high load of messages this can be a
problem - empirical evidence shows that the limit appears to
be around 3300 messages/second.


Solution
--------
To solve this, an alternative interface has been implemented
using the standard SysV IPC "message queue" interface. This
is a POSIX standard, and other parts of SysV IPC is already
used by Xymon.


Operating system configuration
------------------------------
Unfortunately, most systems have default settings for the
message queue parameters MSGMNB (total # of bytes allowed in
the queue) and MSGMAX (maximum size of a single mssage) settings.
E.g. on Linux, defaults for these are 16 kB and 8 Kb, respectively.
Since Xymon by default permits status messages of up to 256 kB
in size, these settings are inadequate.

On Linux, you change the settings via the "sysctl" utility. Most
Linux systems have these settings defined in /etc/sysctl.conf, so
you add these parameters:
	kernel.msgmax=262144
	kernel.msgmnb=1048576
The "msgmax" setting should match your MAXMSG_STATUS setting in
xymonserver.cfg, converted to bytes (MAXMSG_STATUS is in kB, so
you must multiply it by 1024 for the kernel.msgmax value).
"msgmnb" should be 4 times the msgmax setting. After setting these,
either run "sysctl -f /etc/sysctl.conf" or reboot the server
to enable the new settings.

For other systems, please refer to your OS documentation.


Enabling the backfeed queue
---------------------------
The backfeed queue is disabled by default. To enable it, add the
"--bfq" option to xymond (in your tasks.cfg) and restart Xymon.
You can verify that this has been enabled by checking the output
from "ipcs -q" - you should see a line with a message queue owned
by the Xymon userid:

   ------ Message Queues --------
   key        msqid      owner      perms      used-bytes   messages
   0x0a01205e 98305      xymon      666        0            0


Using the backfeed queue
------------------------
xymond_client and xymonnet will automatically use the backfeed queue,
if available.

If you have custom scripts or tools running on the Xymon server, then
you can send messages into the queue using the standard "xymon" utility.
To do so, set the recipient to "0". E.g.

   xymon 0 "status localhost.test green"

will send a status update via the backfeed queue.

NOTE: The backfeed queue is "one-way", so it can only be used for "status",
"data", "drop" and "rename" messages - i.e., any message where xymond does
not return a response.


Checking if the queue is used
-----------------------------
The "xymond" status page includes statistics on the kinds of messages
received by xymond. If the backfeed queue is used, you should see
the number reported in the "backfeed messages" line increase.

You can also query xymond for "senderstats": This lists the number of
connections to xymond from each IP-address. The backfeed queue shows up
as IP "0.0.0.0":

$ xymon 127.0.0.1 "senderstats"
0.0.0.0 1360796
127.0.0.1 1648
10.0.31.155 1397281