Don't be intimidated by the length of this page - we've tried to be as descriptive as possible to get you running with the least amount of trouble. Also, things go much easier if you read all the way through first.

Pre-Requisites

• Java Development Kit 1.2 or higher - go to http://java.sun.com and install the latest JDK if you haven't already. If you don't know what which version you want, then get the JDK 1.3.1 Standard Edition.
• The Spumoni distribution package - You'll need at least the base package, and if this your first time installing Spumoni, you'll also need the lib package, so go download them now, and we'll describe how to install them below.
• Something to monitor - it can be anything queried through a command-line. Examples include ping times, database engine performance, game server statistics, etc. You'll probably want to look in the Spumoni distribution for preconfigured ones.
• A Monitoring Front-End - MRTG, RRDTool, Tivoli, Big Brother, Openview, Unicenter or anything else capable of poling and reporting the results of SNMP queries.

Step 1: Installation

• Pick a good home for Spumoni - I personally like /usr/local/spumoni on unix systems or c:\spumoni on Windows, but it doesn't really matter where you put it.
• Decompress the Spumoni archives into your selected directory - If you're using unix, this can be done with "gzip -d spumoni-yyyymmdd-hhmm.tar.gz" and "tar spumoni-yyyymmdd-hhmm.tar". If you're using Windows, you can use Winzip or an equivalent. Just remember to keep the directory structures intact! Also do this for the lib package if this is your first time installing Spumoni. Now just copy the expanded structure into the home you selected. If you picked /usr/local/spumoni, then your binaries should be in /usr/local/spumoni/bin, your lib files in /usr/local/spumoni/lib, docs in /usr/local/spumoni/doc, etc. Likewise, if you picked c:\spumoni, then your binaries should be in c:\spumoni\bin, your lib files in c:\spumoni\lib, docs in c:\spumoni\doc, etc.

Step 2: Configuration

In the conf/ directory, you'll find several XML files. The global.xml file is where Spumoni's global prefs are stored, and all of the other .xml files define stats programs which can be executed and harvested each time the stats collector runs. You will want to modify at least global.xml and one of the other XML files to get Spumoni monitoring things.

• Modify global.xml to define Spumoni's overall behavior

To do this, we simply specify how we want Spumoni to run, what modules we wish to execute and the SNMP options. Take note of the moduleList attribute - we'll talk more about it below. For now, we'll just tell Spumoni to run all of the linux modules once per invocation and to enable SNMP receive on port 161 with a community string of "public". If you are already running an SNMP daemon, then you'll probably want to pick a port other than 161.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE spumoniPrefs SYSTEM "spumoni.dtd">

<spumoniPrefs

runMode="once"
interval="5"
moduleList="linux"

snmpReceiveEnabled="true"
snmpReceiveVersion="2"
snmpReceiveCommunityString="public"
snmpReceivePort="161"

snmpTrapEnabled="false"
snmpTrapVersion="2"
snmpTrapTargetIp="coffin.darktech.org"
snmpTrapCommunityString="public"
snmpTrapTargetPort="162"

/>

• Modify other XML files to define what stats programs you want to be run/harvested

A good thing to monitor is the ping times to one's ISP. Let's modify the linux_ping.xml file to point to my ISP's DNS server (please substitute your own ;-). The key items here are the program, the regular expression used to extract the values and the names we'll give to those values. Note that the requiredModules attribute is what lets us determine which modules run by matching the global.xml's moduleList attribute above (where we told Spumoni to only run "linux" modules). Also note that for each value we extract in the regexp string (each pair of parenthesis), we declare a varName for it as well as its SNMP OID.

<?xml version='1.0' encoding='utf-8' standalone='no'?>
<!DOCTYPE spumoniPrefs SYSTEM "spumoni.dtd">

<spumoniPrefs>

<statProg
program="ping 216.227.56.20"
regexp="Minimum\s+=\s+(\d+)ms,\s+Maximum\s+=\s+(\d+)ms,\s+Average\s+=\s+(\d+)"
requiredModules="nt"
maxRunTime="10">

<varName snmpOid="1.3.6.1.4.1.12238.55.1" snmpTrapMin="50" snmpTrapMax="80">pingMin</varName>
<varName snmpOid="1.3.6.1.4.1.12238.55.2" snmpTrapMin="50" snmpTrapMax="80">pingMax</varName>
<varName snmpOid="1.3.6.1.4.1.12238.55.3" snmpTrapMin="50" snmpTrapMax="80">pingAvg</varName>

</statProg>

</spumoniPrefs>

Hey, you're now ready to test Spumoni!

Step 3: Testing

• Execute Spumoni in single-run mode

Go to Spumoni's bin directory and type ./spumoni_run.sh (spumoni_run.bat on Windows) to start up Spumoni. Within a few seconds you should see log entries displayed on the screen. Pay close attention when Spumoni starts to run the stats programs and to the results obtained from them. If you get the values you expected, then you're ready to run Spumoni in scheduled-run mode.

• Execute Spumoni in scheduled-run mode

Modify the global.xml file with the two changes below:

runMode="scheduled"
interval="1"

Now go to Spumoni's bin directory and type ./spumoni_run.sh to start up Spumoni again. You should see the stats programs run every one minute. Verify that the values displayed on the screen are what you expect.

• Use an SNMP GET to query your application(s)

Now you're ready to see if you can grab the stats collected by Spumoni using pure SNMP (the whole reason we're here, right?! :-). If you have Net-SNMP installed, you can do this from the command line with their snmpget command. Try the following command to query the localhost on port 161 for OID .1.3.6.1.4.1.12238.55.1 with a community name of "public".

snmpget -Cf -v 1 localhost public .1.3.6.1.4.1.12238.55.1

If you get a good result back, then congratulations! Once you've made it this far, tell your monitoring system (Tivoli, Big Brother, Unicenter, etc.) about your new tree nodes or set up a new front end as described in the next section!

Step 4: More Customization

• Add a GUI front-end

If you don't already have a network monitoring system in place, you can configure MRTG to poll the new values. I'm afraid that setting up MRTG is outside of our scope, but it's pretty easy - go to http://people.ee.ethz.ch/%7Eoetiker/webtools/mrtg/ for specifics. Once you're ready, use the following mrtg.cfg file report what Spumoni and Net-SNMP are now exposing. Note that we're not cheating by running the ping command directly - we're using pure SNMP here!

WorkDir: /home/httpd/html/mrtg
Options[_]: bits,growright
RunAsDaemon: No

Target[spumoni_ping]: .1.3.6.1.4.1.12238.55.13.101.1&.1.3.6.1.4.1.12238.55.15.101.1:public@localhost:161
YLegend[spumoni_ping]: miliseconds
Title[spumoni_ping]: localhost Ping to DNS1 (by Spumoni)
PageTop[spumoni_ping]: <H1>localhost Ping to DNS1 (by Spumoni)</H1>
Legend1[spumoni_ping]: ms:
Legend2[spumoni_ping]: ms:
Legend3[spumoni_ping]: ms:
Legend4[spumoni_ping]: ms:
LegendI[spumoni_ping]: Min Ping:
LegendO[spumoni_ping]: Max Ping:
RouterUptime[spumoni_ping]: public@localhost
MaxBytes[spumoni_ping]: 1000
Options[spumoni_ping]: gauge, integer, nopercent, unknaszero, growright
WithPeak[spumoni_ping]: ymw

• Monitor more applications/statistics -Feel free to use our automagical config file generator! The only real trick is determining what regular expression (regexp) to use to capture the data. If you're not familiar with regexp, post a message with your program's output in the Help forum and someone may be able to help you.

• Set up Spumoni to start up like a real daemon - If you're like me, you prefer to start Linux/BSD daemons using init.d scripts. Well, Spumoni has one that works great, but you'll need to create a symbolic link to java to make it work cleanly (this is because of how all Java programs run and report themselves in Linux's threading system, but that's another discussion). Just go to your $JAVA_HOME/bin directory and type "ln -s java spumoni". Then go to Spumoni's bin directory and type "cp etc_rc.d_init.d_spumoni /etc/rc.d/init.d/spumoni". You should now be able to start, stop and status Spumoni like any other daemon. Remember to create a symbolic link in /etc/rc.d/rc3.d if you want it to auto-start during bootup!

Step 5: Contribution (please don't skip this part!)

Spumoni is a Free project donated by Scott McCrory and others. Please show your gratitude by giving back to Spumoni in any way that you're capable of. If you've created a config file for an application that you think others would benefit from, please email it to Scott and he'll add it to the distribution and credit your assistance. The same goes for coding help, bug fixes, testing, documentation and forum help. Thanks in advance!