Purpose

The instructions and script that follow are intended to be used to monitor 1 to 4 temperature readings from a ControlByWeb's 4-temp/2-relay temperature monitor module OR 1 to 8 temperature readings from the X-300 8-temp/3-relay 7-day programmable thermostat module and report temperature readings back to a Xymon monitoring server for logging, graphing and alerting.

Here you will find the most current versions of our:

• Instructions on integrating, monitoring, graphing and alerting on the output from the xymon_cbw_temp.sh script with a Xymon server
• xymon_cbw_temp.sh - Xymon/ControlByWeb temperature module & X-300 thermostat module monitoring script

Related Scripts

We have also written several other scripts that you may find useful. You may find them HERE

Instructions

ControlByWeb Temperature Module Configuration

First you need to do some basic configuration of the ControlByWeb temperature module. Instructions are included with the device, but the basic steps are as follows:

• Connect: Connect to the device's default IP address using a web browser: http://192.168.1.2/setup.html (USER is blank, default password is webrelay)
• Network Tab: Set up its network settings to match your network environment.
• Email Tab: Optional since we will be alerting using Xymon.
• Password Tab: Recommended, but also optional.
• Main Tab: Set the temperature scale (Celsius or Fahrenheit). The rest of the options on this tab are optional for our configuration.
• Sensor1 - Sensor4 Tabs: The only setting required for our configuration is the "Sensor Address". Choose the appropriate "Sensor Address" from the drop down list. Set the "Sensor Description" to aid in troubleshooting later if you like. The rest of the settings are optional, but can be useful, especially in the case of operating one of the local relays when a temperature threshold is crossed.
• Reboot: Reboot the ControlByWeb module to complete the network configuration, and then try connecting to it at its new IP address.

Xymon Configuration

Install the custom external script

- Copy the bash shell script below into ~xymon/server/ext/xymon_cbw_temp.sh
- Set the ownership and execution permissions on the script

chown xymon:xymon ~xymon/server/ext/xymon_cbw_temp.sh
chmod +x ~xymon/server/ext/xymon_cbw_temp.sh

Edit script to match your environment

- The script is pretty well documented, and you only need to modify a few of the pre-configured variables to get started:

• Local system binaries: (GREP, TR & CURL)
• MODULE - The IP address or FQDN of the ControlByWeb device and its TCP port. For example: host.example.com:port. The ":port" is optional but may be included if your ControlByWeb device is configured to listen on a port other than the default HTTP port of 80.
• USER - Leave blank for a ControlByWeb 4-temperature module
• PASS - Set to "webrelay", or set to same password used when you configured ControlByWeb device
• COLUMN - Set to the name of the Xymon test
• ZONES - These are documented in the script and should be pretty easy to understand there
• SCALE - Set to desired temperature scale (e.g.: "C" or "F") Must match what the module is configured to display as. This is for display purposes only.
• ADMINMSG - (optional) An administrative message that will be added to the top of the Xymon report page

Tell Xymon (hobbitlaunch) to start running the new script

- Tell Xymon to start running the new external script by adding these lines to ~xymon/server/etc/hobbitlaunch.cfg:

[cbwtemp]
      ENVFILE $BBHOME/etc/hobbitserver.cfg
      CMD $BBHOME/ext/xymon_cbw_temp.sh
      INTERVAL 5m

- Wait a few minutes and you should see a new column called cbwtemp on your Xymon page
- Click on the cbwtemp icon and you should see the new cbwtemp test reading(s) with a timestamp of the latest update similar to the image below:

Let's get to the graphing!

- It is a two step process to get Xymon to begin graphing our data.

• First we need to tell Xymon to start putting our temperature readings into RRD (Round Robin Database) files
• Next we need to tell Xymon how we want our graph to look, and what info we would like printed on it

- Edit ~xymon/server/etc/hobbitserver.cfg.
- Find the TEST2RRD line and add our new test to the end like so:

TEST2RRD="cpu=la,disk,inode....hobbitd,clock,lines,cbwtemp=ncv"

That tells Xymon to map our new column called cbwtemp to rrd file(s), and that Xymon should send the data through the built-in NCV (name-colon-value) module.

- Tell Xymon to also include our new cbwtemp graph on the trends page by adding it to the GRAPHS definition line in the hobbitserver.cfg file like so:

GRAPHS="la,disk,inode,qtree...hobbitd,clock,lines,cbwtemp"

- Add this line to the end of your hobbitserver.cfg file.

SPLITNCV_cbwtemp="*:GAUGE"

That tells Xymon to create a series of RRD files, one for each NCV pair reported by the xymon_cbw_temp.sh script for the cbwtemp column. The datasets will be of type GAUGE (since temperatures go up and down and are not always-increasing counter type readings). The files Xymon creates will be called ~xymon/data/rrd/host.example.com/cbwtemp,Location.rrd where each Location will be one of the locations you set up in the ZONES variable in the xymon_cbw_temp.sh script.

Xymon needs to be restarted at this point to pick up the new configurations changes/additions. Alternately, you may just kill any running hobbitd_rrd and hobbitd_channel processes and Xymon will restart them using the new settings from hobbitserver.cfg.

- At this point we should verify that our new rrd files exist:

$ ls -1 ~xymon/data/rrd/host.example.com/cbwtemp*

/usr/local/xymon/data/rrd/host.example.com/cbwtemp,Office.rrd
/usr/local/xymon/data/rrd/host.example.com/cbwtemp,Outside.rrd
/usr/local/xymon/data/rrd/host.example.com/cbwtemp,ServerRoom.rrd

And then we can also verify that our expected data is in these files.
We should verify three values: the name <name>, type of test <type>, and last value received <last_ds>:

$ rrdtool dump ~xymon/data/rrd/host.example.com/cbwtemp,ServerRoom.rrd | grep "name\|type\|last_ds"
      <name> lambda </name>
      <type> GAUGE </type>
      <last_ds> 78.1 </last_ds>

Wait! What? lambda?? Shouldn't that say ServerRoom?? No, this is correct. When using SPLITNCV the dataset names in each of the rrd files will be lambda. Notice though, that the type is GAUGE, and that the last_ds value of 78.1 degrees Fahrenheit looks like a reasonable temperature reading for our server room (ok, not really... but we're just demonstrating here). So far, So good. You may check the other cbwtemp,*.rrd files if you like to confirm they are OK too.

Now if you view the cbwtemp status page, you will notice that there is still no graph being drawn. That is OK, because we haven't configured Xymon's hobbitgraph.cfg file to define how Xymon is supposed to graph our new column yet.

**note to waa** Remember to explain how to use "rrdtool tune" to set the MIN to a negative number if you are expecting negatives. Alternately, maybe there is some more proper documentation for the SPLITNCV_testname=.... line in the hobbitserver.cfg file so that may be configured automatically at time of the rrd file's creation.
Revision - 20100-07-10: No need, since this was just addressed as a bug fix yesterday. See: Revision: 6324

- Edit ~xymon/server/etc/hobbitgraph.cfg and add the following lines: (see explanation below)

[cbwtemp]
        FNPATTERN cbwtemp.(.+).rrd
        TITLE Temperature
        YAXIS Fahrenheit
        DEF:p@RRDIDX@=@RRDFN@:lambda:AVERAGE
        LINE1.5:p@RRDIDX@#@COLOR@:@RRDPARAM@
        GPRINT:p@RRDIDX@:LAST: \: %5.1lf (cur)
        GPRINT:p@RRDIDX@:MAX: \: %5.1lf (max)
        GPRINT:p@RRDIDX@:MIN: \: %5.1lf (min)
        GPRINT:p@RRDIDX@:AVERAGE: \: %5.1lf (avg)\n

- The hobbitgraph.cfg entry explained:

[cbwtemp]    : Defines the name of the graph and must match the name 
               of the status column to have this graph appear on the
               cbwtemp status page 
FNPATTERN    : Describes what rrd files(s) should be read to generate the 
               graph for this column. In our case we are telling it to 
               look for cbwtemp(anything).rrd files.
TITLE/YAXIS  : These define the graph's title and y-axis legend
DEF          : 
LINE1.5      : This says draw a line of thickness "1.5"
GPRINT       : The next sets of four lines print out the Last, Maximum,
               Minimum and Average vales in the rrd file for our tests

- We're done!
- Now, reload the cbwtemp page and you should start seeing something similar to the image below:

- Special thanks to goldfndr in the #xymon IRC channel on freenode for motivating and helping me to convert these instructions to use SPLITNCV instead of NCV.

xymon_cbw_temp.sh