How to Install
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
- Java Development Kit 1.2 or higher - go to
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,
or anything else capable of poling and reporting the
results of SNMP queries.
Step 1: Installation
- Pick a good home for Spumoni - I personally
on unix systems or c:\spumoni
on Windows, but it doesn't really matter where you
- 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,
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
- 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.
<!DOCTYPE spumoniPrefs SYSTEM "spumoni.dtd">
- 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.
version='1.0' encoding='utf-8' standalone='no'?>
<!DOCTYPE spumoniPrefs SYSTEM "spumoni.dtd">
Hey, you're now ready to test Spumoni!
Step 3: Testing
- Execute Spumoni in single-run mode
Go to Spumoni's
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:
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 .188.8.131.52.4.1.12238.55.1 with a
community name of "public".
snmpget -Cf -v 1 localhost
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
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
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!
Title[spumoni_ping]: localhost Ping to DNS1 (by Spumoni)
PageTop[spumoni_ping]: <H1>localhost Ping to
DNS1 (by Spumoni)</H1>
LegendI[spumoni_ping]: Min Ping:
LegendO[spumoni_ping]: Max Ping:
Options[spumoni_ping]: gauge, integer, nopercent,
- 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
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!