Weekend Project: Monitor Your Server with StatusNet Updates


Summer is almost here; do you really want to spend it sitting indoors and monitoring the health of a running server or daemon? Rather than resign yourself to that fate, why not set up your system to post important messages, from regular status updates to emergency messages, through a microblogging service like Identi.ca? It’s easier than you might think.

There are several different ways you can make use of a microblogging service to keep an eye on your server (or, for that matter, desktop machine), depending on what kinds of message you want to receive. You can tail log files and repeat the output in a feed, run a periodic cron job to collect statistics and send out the results as a form of “heartbeat monitor,” or have batch processes send notifications when they complete. You can even configure existing open source monitoring services to use the service directly, or through email- or SMS-gateways.

Systems administrators have been using Twitter’s public API to do this sort of thing for years, of course.  Searching on the Web returns scores of hits for most combinations of “twitter,” “monitor,” and a particular service name.

StatusNet is a free software service that can do what Twitter does and more. Identi.ca is the most popular public StatusNet instance, but the software is also available for download as a quick-install option on shared web hosting services, and as a commercial service for companies and large organizations.

Twitter and StatusNet APIs

For compatibility, StatusNet implements the Twitter API, including some undocumented features. In almost all cases, adapting a Twitter monitoring script to post update messages to Identi.ca or your personal Myserver.status.net instance is a straightforward operation, because it is likely to use only the basic posting methods. However, before getting started, it’s a good idea to look at a few of the other differences.

First, Twitter allows any user to run a “private” status update feed, in which posts are not visible to the general public, and all subscription requests must be approved by the account holder.  Identi.ca does not offer this option at present, nor is it provided in the free StatusNet cloud options; one of the guiding principles of Identi.ca was to make all of the content available under open, Creative Commons license terms.  Consequently, you should not fire off sensitive company information to an Identi.ca feed, because it will be public.

On the other hand, you can run your own instance of StatusNet on your own web server, and keep it as private as you like, including making the update timeline visible only to logged-in users, and companies interested in server monitoring might find one of the private, paid StatusNet offerings suitable for the same reason. In addition, for those with security concerns, note that StatusNet does support SSL authentication, just like Twitter.

Distinct StatusNet instances can pass messages back-and-forth to each other, which offers you more flexibility. You can set up a feed for your server monitor on one StatusNet instance and subscribe to it with your normal Identi.ca account. One reason you might want to do that is that StatusNet is not limited to the 140-character-per-message restriction used by Twitter, so you can choose a longer service from existing public instances (such as 280.status.net, or unlimited.status.net), or set up a private instance and fix your own message-length limits. You also do not have to worry about a private StatusNet instance going down suddenly if Ashton Kutcher gets arrested, and in practice the public services like Identi.ca have not suffered from the “fail whale” outages that plague Twitter on a regular basis.

StatusNet also provides more interoperability with other messaging formats than Twitter does. Twitter allows you to link a mobile phone to an account so you can send and receive status updates over SMS. Identi.ca supports SMS as well, plus sending and receiving messages with XMPP instant messaging (such as Jabber or Google Talk accounts), and via email. Other StatusNet services may or may not support all of these methods; they are optional plugins that can be activated by the site administrator.

Twitter provides fairly complete documentation of its native API on its web site. But StatusNet also has a page on its documentation wiki dedicated to tracking its own implementation of the API, so that is the best place to look if you run into problems. Basic updating, however, is a piece of cake.

Sending Your First Updates Through the API

The simplest way to get started is with cURL, so that you can send API requests directly from the command line. To send a status update request for Identi.ca, run curl -u theUsername:thePassword http://identi.ca/api/statuses/update.xml -d status=’Here goes nuthin‘, substituting the username and password. Identi.ca will reply with an XML response, including the status update itself and user account information.

Breaking down this request, the username:password parameters are followed by the call to the API method itself, which builds on the API root of the StatusNet server. For Identi.ca, this is http://identi.ca/api.  For another StatusNet instance, it may be different, depending on where you installed StatusNet.

The official documentation recommends that you substitute the account ID number in place of the username; the account ID is included in the XML response to the status update, and on Identi.ca is also visible on each user’s public page. For quick testing, however, the username will suffice.

You can tag your status update with location information if needed, either through the -d lat=’LATITUDE’ -d long=’LONGITUDE’ parameters, or the -d place_id=’PLACE’ parameter.

Automating: Several Methods

You can use cURL to easily send out status reports from shell scripts, which enables you to monitor batch processes or run periodic cron jobs that report back through StatusNet.  For example,

# collect info
UPTIME=`uptime | cut -d” ” -f4,5,6`
if ps ax | grep -v grep | grep asterisk > /dev/null
    statusupdate=”${UPTIME} – Asterisk is running”
    statusupdate=”${UPTIME} – Asterisk is not running!!”
# report it
curl -u myserver: http://identi.ca/api/statuses/update.xml -d status=’${statusupdate}’ >/dev/null 2>&1

…simply retrieves the system uptime, and checks whether or not there is a process named asterisk running, then sends out a status update with the results. You could execute this script regularly by placing it in your crontab file. Run sudo crontab -e to open it, then add a line such as 01 * * * * /usr/local/bin/my_denting_asterisk.sh to schedule when it should run (in that example, one minute past the hour, every hour).

Clearly, you can gather much more detailed information, and in many cases you do not want your cron job reporting regularly that nothing has happened, so you perhaps would skip sending out the update unless the process has died.

But there are even easier options, including StatusNet’s ability to accept incoming email messages as status updates. First, to turn on this feature on Identi.ca, go to your account’s email settings (http://identi.ca/settings/email). The top box labeled “Address” is the external email address associated with your profile, which you use to verify ownership of your account. The lower box labeled “Incoming email” allows you to generate a secret email address that you can use to post updates.

The wording in the box is confusing, but do not worry: click on “New” and an address consisting of a long alphanumeric string in the @identi.ca domain will be automatically created. Now, you can copy that email address to the /root/.forward file on your Linux machine. Any script that send an alert message to root will automatically have it forwarded to the status feed on Identi.ca. Obviously, you should again use caution here for security-sensitive servers; it is probably wisest to use this feature on private StatusNet deployments.

Of course, you can also activate SMS and XMPP delivery of status updates if you want; in reality, these options do not make it simpler to get the status updates out of the machine, but they give you multiple paths to make sure they are delivered.

Direct Messages

One other option to consider is sending a direct message rather than a public status update. If you don’t want the world reading about your CPU and process load, but you don’t want the overhead of administering your own private StatusNet server, this provides an in-between solution: more private, but without strict guarantees.

The syntax for a direct message is similar to that for a status update, with the addition of a recipient parameter named user, and calling the message body text. For example: curl -u theUsername:thePassword http://identi.ca/api/direct_messages/new.xml -d user='<em>SomeOtherUsername</em> -d text=’I think we need to talk about the Asterisk server, fast.’

One other important distinction is that direct messaging on Identi.ca is only allowed between two accounts that are both subscribed to each other. So theUsername and SomeOtherUsername must be mutual “followers” for the above command to work. Double-check before you start relying on this system for important alerts.

Further Work: Monitoring Solutions, Attachments, and Output Parsing

Individual monitoring scripts are fine for a small service, such as a home office or personal Web server, but for most professionals, they don’t scale. Luckily a lot of users who deploy network monitoring solutions have already integrated basic Twitter output, which you can easily adapt to a StatusNet instance as shown above, and take advantage of the longer message lengths to get better reports and built-in email connectivity.

For example, Zenoss has a community-contributed script for sending out alerts with Twitter. Because it uses the basic statuses/update API method, it is instantly adaptable to StatusNet. Nagioscan do the same thing.

Monit, on the other hand, has built-in email alerts, so it can be used directly with the Identi.ca email-updating system. Doing the same thing with Twitter requires going through a separate service.

If you really want to explore reporting server status with StatusNet, you might find a good use for StatsuNet’s built-in support for attachments via the media parameter. Just append a file name to your API call such as -d media=’/tmp/daily_use.png’ and it is posted along with the status update. Apache could generate and post traffic graphs every night. Here again, to duplicate this functionality in Twitter requires using an outside image-posting service.

Finally, although all of the examples given here essentially ignore the output returned by the StatusNet server, it might be wise to try and parse it and make sure that nothing has gone wrong. Though the examples used XML output, the server can also return its response in JSON format; just call update.json instead of update.xml.

Who knew getting your server to talk was so simple? Just be sure to take it easy at first; you might find that your servers start chattering so much about their status that you start to tune them out…