View: HTML | Text | PS | PDF | RTF | Wiki | DocBook | DocBook Inline | changelog | about this header Circle Jeff Boweron  
Using stoker_mon for Stoker Under Ubuntu Linux

Using stoker_mon for Stoker Under Ubuntu Linux

This document describes some of the details behind stoker_mon for Ubuntu Linux. The developer is incredibly lazy, undisciplined, and incompetent so please forgive the rough edges.


Table of Contents
1. What is stoker_mon?
1.1. stoker_mon Features
2. Getting stoker_mon
2.1. stoker_mon Prerequisites
3. The Scripts
3.1. stoker_get.sh
3.2. stoker_put.sh
3.3. stoker2csv.sh
3.4. stoker_creategraph.sh
3.5. stoker_mon
4. Configuring stoker_mon
5. Configuring Apache
6. Using stoker_mon
6.1. Main Page
6.2. Stoker Configuration Page
6.3. Edit Cook Page
7. Getting Help
A. About Me

1. What is stoker_mon?

stoker_mon aims to be a web-based interface allowing you to semi-securely control one or more Stokers from Rock's BBQ. It consists of a few shell scripts and some PHP/JavaScript based web pages and a single configuration file.

stoker_mon is currently in an Alpha State. Please don't expect it to be a polished gem anytime soon.


1.1. stoker_mon Features

stoker_mon aims to be a fully functional (and still moderately secure) web interface to the Stoker. For my own usage I think I'm getting pretty close, but I've got a long way to go. However, the following features are available:

  • Support for an arbitrary number of probes, blowers, and support for multiple Stokers.

  • The ability to provide a conduit between a proper webserver on a public IP address and your protected Stoker, no need to expose your Stoker to the Internet directly and you can use Apache's tools to help protect access.

  • A set of shell scripts able to read and write JSON data to the Stoker.

  • The ability to view a temperature graph of an active cook.

  • The ability to auto-detect your Stoker's configuration.

  • A liveness check to see if your Stoker responds to pings.

  • The ability to start and stop monitoring a Stoker.

  • The ability to store and name old cooks.

  • The ability to modify an existing cook, including setting probe names, target temperatures, and assign a blower (although I like the paradigm of assigning each blower to a probe instead of assigning some probes a blower).

  • Most importantly, the ability to run on a native Linux platform and, therefore, on any platform through VirtualBox, KVM, VMWare, or Xen without spending a single cent.


2. Getting stoker_mon

stoker_mon can be found at http://www.ebower.com/stoker/stoker_mon.tar.gz in the form of a nightly build. I'm releasing this under the permissive Apache license which means it should not be GPL-infected, however it does rely on certain tools (not bundled) that may be under more restrictive licenses.


2.1. stoker_mon Prerequisites

stoker_mon assumes you're running on Ubuntu. I currently run Lucid (10.04) on my servers and Maverick on my desktop. There are no tight dependencies on the version you run, however you may be better off running this on Lucid since it's a Long Term Support release and it's unlikely an update to PHP or Apache will break things. I run my webserver in a VirtualBox VM which is probably the best method to get things working under Windows or (yuck!) OSX.

I use the JSON interface from the Stoker which means you'll need version 2.6.0.226 or later. You can find the software on Kaytat's website and the JSON interface was defined under the July 31, 2009 entry.

To actually pull the information I choose to use curl which is a bit better than wget in that it supports proxies and the proper POST output to set the Stoker. I also use gnuplot to generate the graphs, between these two programs you should be all set. Of course, no system is complete without grep, sed, awk and probably a host of other programs that should be there by default.

If you want to use the web interface you'll want to install Apache2 and the PHP extensions. For the most part the pages are simple enough to just work, but I've only tested extensively with Google Chrome on Ubuntu Maverick (32 and 64 bit flavors) and a bit with the stock Android browser on Froyo.

On a stock Ubuntu Server install you'll need to run the following to enable stoker_mon:


sudo apt-get install curl gnuplot-nox apache2 libapache2-mod-php5

3. The Scripts

The scripts can be used on their own if you like, especially if you think my mad web design skillz are, well, abysmal is a bit complementary... They're currently not very extensible and make use of many defaults that may only be relevant for my own system, but I did try to put most of the paths into variable names near the top. Each one serves its own function as described below.


3.1. stoker_get.sh

The workhorse of the group. This program simply nabs the JSON output from the Stoker that lives at the IP provided as a parameter. For example, stoker_get.sh 192.168.1.100 will pull the relevant URL from the stoker at 192.168.1.100 and output to stdout the results.


3.2. stoker_put.sh

This program will do the reverse of stoker_get.sh in that it will take a filename and IP as parameters and push the config file to the Stoker. The config file is largely the output of stoker_get.sh edited to only include the JSON information and with the changes you see fit. Obviously the Stoker may reject invalid files or ignore changes that don't make sense (changing the probe ID, for example) but I make no attempt to validate the uploaded file. A valid command would be stoker_put.sh turkey_cook.json 192.168.1.100.


3.3. stoker2csv.sh

This program will take the output of stoker_get.sh and append it to the output of a gnuplot-formatted file. It does a little munging and massaging of the data, hopefully with a happy ending. It creates a metadata file on every pass, this file has information about the probe names and some other cook details. It's a bit wasteful to create it every time the function is called (it's called by default once every 10-20 seconds for every Stoker you monitor, this is controlled in the stoker_mon script) but it also means I've got up-to-date information at all times. Just run stoker2csv.sh 192.168.1.100.json and it will create a bunch of similar-looking files.


3.4. stoker_creategraph.sh

This script takes the gnuplot-formatted output of stoker2csv.sh and converts it into a PNG formatted image. I'm also wasteful here in that I create a graph every 10-20 seconds (again, see stoker_mon to edit this period) but it does prevent a Denial of Service issue if I create the graph on-demand (essentially I could create 1000 connections to create the graph 1000 times and bring the system down). A better method is to check the file dates, but that's a longer term strategy. You can run stoker_creategraph.sh 192.168.1.100.json.gnuplot to create the image file.


3.5. stoker_mon

This script is the daemon that ties everything together. To create an automatic set of graphs just run stoker_mon 192.168.1.100& (note the ampersand, you may also want to use stoker_mon 192.168.1.100 >/dev/null& instead to suppress the output) and it will automatically create some mostly meaningful files for you, by default in stoker/cooks/.

The files are prepended with the date and time of the start of the cook followed by the IP address of the Stoker. From there, .json is the last raw output from the Stoker. The .json.gnuplot file is the record of the cook in a gnuplot-friendly format and .json.gnuplot.meta holds the metadata from the cook while .json.gnuplot.png is the graph of the cook. You may find some files ending in .tmp which should be ephemeral, but an improperly stopped cook (using kill or restarting Apache) could leave behind some clutter. Finally, there's a special file named with the IP of the Stoker and ending in .active which indicates a cook is currently active. The file contains the name of the associated .json file. Deleting this file is the best way to stop a monitoring session as it will complete all activities in the current cycle and then gracefully exit.


4. Configuring stoker_mon

Right now configuring stoker_mon consists of editing a single file with a list of the Stoker IP addresses you want to be able to monitor. Edit stoker/config/stokers.conf with a line for each Stoker like the following:


192.168.1.100=My Stoker

Note that you can use spaces in your Stoker name and it's pretty arbitrary - it simply needs to be defined here because there is no place for it in the Stoker itself.

That's the only thing you should need to touch. You can also look in each of the scripts and see what tunable parameters I've got listed at the top. About the only other useful parameter is the interval variable in stoker_mon. I pull the data, process the data, create the graph, and then wait interval seconds before repeating the process. 10 seems like a decent number, but note that on my system this means 15-20 seconds between readings since it takes a while to get and process the data.


5. Configuring Apache

Detailed Apache configuration is a bit outside the scope of this document. I'm going to assume that you've got a working Apache website and that you can access it from wherever you want. In a nutshell, if you open up a browser and point it to your web server's IP address you should see an "It works!" page. If not, you may need to check your server's IP, if you're running in VirtualBox make sure that your network interface is set to "Bridged", and if you're trying to access the page from outside make sure your router is set up to forward the appropriate port (typical port 80) to the right IP address. Also note that some ISPs block incoming traffic, Comcast used to block port 80 so you'll need to use something like port 8000 or, even better, switch to Verizon FiOS who doesn't block anything. Verizon Wireless, on the other hand, seems to block all incoming traffic. You can also look at my DNS Tutorial to get yourself an easy-to-remember hostname.

Now that everything's hopefully working fine, what do you need to do to get stoker_mon to run? Well, I put stoker_mon in /var/local/stoker/ to keep it separate from my core web server files (which I like to keep with enhanced permissions in case my web server gets hacked). In order to enable this you'll need to edit /etc/apache2/sites-available/default and add the following lines between your <VirtualHost> tags:


Alias /stoker "/var/local/stoker/"
<Directory "/var/local/stoker/">
Options -Indexes MultiViews FollowSymLinks Includes
AllowOverride None
Order allow,deny
Allow from all
</Directory>

I also want to prevent people (including perhaps the Google and Yandex webcrawlers) from touching my Stoker's config. As such I've done a cop-out method of security and moved all of the write-access pages to the protected directory and set up a modicum of security. Note that this is far from actually secure, your username and password are sent in plaintext so use a password you don't care about or do what I do, set up an SSH proxy from your remote device to your house to encrypt everything. If you don't have an SSL-enabled website now, you may want to consider configuring one. You can easily get a free cert that only requires yearly maintenance and it will protect you from a slew of potential snooping issues. Please see my SSL configuration guide for details on how to obtain a free cert and install it on Apache2.

This needs two steps, first you'll need to create an Apache password file by running sudo htpasswd -c [filename] [username]. Put this file someplace logical like /etc/apache2/passwd and definitely not someplace other people can get to it. From there you'll need to add an entry similar to the one above. Here's the entry for the read/write directory:


Alias /stoker/protected "/var/local/stoker/protected/"
<Directory "/var/local/stoker/protected/">
AuthType Basic
AuthName "!!!Are you connected via a secure tunnel? Not SSL-enabled!!! Stoker Read/Write Access"
AuthBasicProvider file
AuthUserFile [passwd_file_path]
Require user [username]
Options -Indexes MultiViews FollowSymLinks Includes
AllowOverride None
Order allow,deny
Allow from all
</Directory>

6. Using stoker_mon

For quite some time the exact screenshot will be mostly meaningless since it'll probably change dramatically, but this should give you a flavor for my lack of style (and lack of style sheets) when it comes to HTML design.


6.1. Main Page

The main page is designed to be fairly benign to publish to the world. It includes some basic information about the project and, if there's an active cook, it will show you the graph(s). Below is a screenshot of the main page with an active cook. A few links to other sources of information, a link to manage your Stoker, a graph showing an active cook, and a link to download stoker_mon. The graph below isn't a good indication of what a Stoker is used for, I'll update it the next time I do a real cook and remember to grab a screenshot.

Figure 1. stoker_mon Main Page (with cook)


6.2. Stoker Configuration Page

If you've properly authenticated you can configure the Stokers. For now all you'll be able to do is see if the Stoker is up (accessible via an ICMP echo or ping) and there are links to start or stop a cook.

Figure 2. stoker_mon Stoker Configuration Page


6.3. Edit Cook Page

For active cooks you can edit the Stoker parameters as you see fit. For old cooks you can only modify the cook name.

Figure 3. stoker_mon Edit Cook Page


7. Getting Help

The best way to get help, provide feedback, or make feature requests is to email me at stokermon@ebower.com. Once stoker_mon is ready for release I'll look into hosting it at one of the open source project pages where we can better formalize the project - assuming it ever gets that level of momentum.


A. About Me

My name is Jeff Bower, I'm a technology professional with more years of experience in the telecommunications industry than I'd care to admit. I tend to post with the username jdbower on various forums, including Komodo Kamado, Android Central, VirtualBox, and MakeMKV. Writing these documents is a hobby of mine, I hope you find them useful and feel free to browse more at https://www.ebower.com/docs.

I also enjoy cooking, especially outdoors with my Komodo Kamado and using my Stoker. Take a look at my recipes stored at https://www.ebower.com/recipes.

If you've got any questions or feedback please feel free to email me at docs@ebower.com or follow me on Google+ or Twitter.