[wiki:howto <- Back to the HOWTO section]

= How to setup Xymon server =

 * Audience: Advanced sysadmins
 * Requires: MacPorts >= 1.9, xymon-server

----

== Introduction ==

Xymon is a tool for monitoring servers, applications and networks. It collects information about the health of your computers, the applications running on them, and the network connectivity between them. All of this information is presented in a set of simple, intuitive webpages that are updated frequently to reflect changes in the status of your systems.

The Xymon client software (port name "xymon") is collecting information on the host you want to monitor. It gathers everything into a report and sends it towards the Xymon server (port name "xymon-server") over TCP. The destination port to connect to the Xymon server is 1984 in reference to big brother http://en.wikipedia.org/wiki/Big_Brother_(Nineteen_Eighty-Four).

----

== Installation ==

Install Xymon server:

{{{
sudo port install xymon-server
}}}

Note: xymon-server port doesn't support non-default compilers. Make sure your binpath parameter in macports.conf remains set to the default.

== Variants ==

=== SNMP ===

There's only one variant available for the moment: snmp. It provides undocumented and experimental SNMP support within xymon. This variant is disabled by default. To enable it:

{{{
sudo port install xymon-server +snmp
}}}

You may search the Internet for "hobbit-snmpcollect", "xymon-snmpcollect", "hobbit-snmphosts.cfg" or "xymon-snmphosts.cfg" for more info about it. There's also an introduction here: http://www.xymon.com/archive/2008/01/msg00378.html

----

== Configuration ==

Note: Configuration of Xymon server implies several changes of your system and will probably require a reboot of your system. Make sure you understand every step before executing it.

=== Step 1: ''Tune the number of shared memory segments'' ===

Xymon server needs at least 9 IPC shared memory segments to run. Unfortunately Mac OS X up to v10.11 ships with a default max of 8.

Check how many shared segments a process can use on your system:
{{{
$ sysctl kern.sysv.shmseg
}}}
And the max number of shared segments system-wide:
{{{
$ sysctl kern.sysv.shmmni
}}}

If the first number is < 9, you need to tune your system before trying to start xymon server (doing so will make the whole system to crash).

Run the following commands to increase your shared segments:
{{{
$ sudo bash -c "echo kern.sysv.shmmax=16777216 >> /etc/sysctl.conf"
$ sudo bash -c "echo kern.sysv.shmmni=128 >> /etc/sysctl.conf"
$ sudo bash -c "echo kern.sysv.shmseg=32 >> /etc/sysctl.conf"
$ sudo bash -c "echo kern.sysv.shmall=4096 >> /etc/sysctl.conf"
}}}

Reboot your system to activate the change. 

More information about shared memory segments on Mac OS X can be found here: http://support.apple.com/kb/HT4022

=== Step 2: ''Configure your apache web server'' ===

Make sure the following line is uncommented in your /etc/apache2/httpd.conf:
{{{
LoadModule cgi_module libexec/apache2/mod_cgi.so
}}}

Xymon "make install" ends with:

''You must configure your webserver for the Xymon webpages and CGI-scripts.
A sample Apache configuration is in /opt/local/lib/xymon/server/etc/xymon-apache.conf
If you have your Administration CGI scripts in a separate directory,
then you must also setup the password-file with the htpasswd command.''

So the following commands should do it:
{{{
$ sudo mv /opt/local/lib/xymon/server/etc/xymon-apache.conf /etc/apache2/(other|sites)/
$ sudo /usr/sbin/apachectl restart
}}}

The apache2 configuration directory should be /etc/apache2/other/ on __Mac OS X__ and /Library/Server/Web/Config/apache2/sites/ on __Mac OS X Server__.

=== Step 3: ''Make Xymon user part of the admin group'' ===

We achieve this with the Directory Service command line utility:
{{{
$ sudo dscl . -append /Groups/admin GroupMembership _xymon
}}}

Note: on old Mac OS the Xymon user should be "xymon"

=== Step 4: Configure Xymon ===

Under /opt/local/lib/xymon/server/etc/ you'll find a set of configuration files. Some variables in xymonserver.cfg needs to be tuned:
 * XYMONSERVERHOSTNAME
 * XYMONSERVERIP
 * XYMONSERVERWWWNAME

The hosts.cfg should also contain all your monitored hosts. You'll find more info on how configuring xymon here: http://xymon.sourceforge.net/docs/hobbit-config.html

The xymon-server port install the default configuration files from the distribution with the version number as suffix. Once you don't need those default config files, you may remove them. For example with the 4.3.0 version you should execute:
{{{
$ sudo rm  /opt/local/lib/xymon/server/etc/*.4.3.0
}}}

=== Step 5: ''Start Xymon server'' ===

A startup item has been generated that will aid in starting xymon with launchd. It is disabled by default. Execute the following command to start it, and to cause it to launch at startup:

{{{
$ sudo launchctl load -w /Library/LaunchDaemons/org.macports.xymon-server.plist
}}}

=== Step 6: ''Allow incoming connections on Xymon port 1984'' ===

If your __Mac OS X__ firewall is enabled, you'll be asked to allow xymon -> accept.

On __Mac OS X Server__, make sure your ipfw rules will allow incoming TCP connections to port 1984.

=== Step 7: ''Check the status of your Xymon server'' ===

To view the Xymon webpages, wait 5 minutes to give Xymon time to generate the index page, open your web browser and go to http://localhost/xymon/

----

== Operate Xymon server ==

The Xymon server can be stopped/started and restarted with the following command:

{{{
$ sudo -u [xymon|_xymon] /opt/local/lib/xymon/server/xymon.sh [stop|start|restart]
}}}

----


[wiki:howto <- Back to the HOWTO section]