2005-08-29
Updated: 2007-01-17

Jason Schoonover

	1. Summary
	2. Details
	3. Configuration
	4. Example

This plugin is designed for the paranoid;  it will allow you to check 
the status of unnoc from any location in the world (assuming of course 
that your cell phone has a decent signal).

Requirements:

	A dedicated email address on your email server
	A cell phone with SMS and a valid email address

1. In short, this is what it does:

It will check an email account every 1 minute and if it sees a "system 
status" line in an email, if it does see that, then it will send an
email out to your pager/phone and display the system status in an SMS
message.  So if you're on vacation and are wondering if everything is
okay or not, simply send an email to unnoc@domain.com (this address 
is configurable) and wait 1 minute, it will then page you of the 
status of unnoc (this one has also saved me several times).


2. Here's a more detailed explanation of how to set it up:

Setup an email account on your email server called unnoc@domain.com, or
whatever.  Put the credentials and information into the unnoc.conf 
config file, include username and password.  Include your phone's email 
address in the valid_emails option, you can include any cell phone or 
email address that you want to send to. (If you don't have an email 
address for you cell phone, this is easy to set up, go to your 
provider's homepage and follow the instructions).

Once you've set all the options in the unnoc.conf file, setup 
system-status.pl to run every 1 minute (or longer if you wish) in then
unnoc.conf file.  Once you've done this, it will check the email 
account every one minute.

Now if you send an email to unnoc with the line "system status" in body,
it will read the status of the MySQL db and send back problems only in a
shortened response to your phone. I know what you're thinking: SECURITY
RISK.  However I don't think it is because of the way it's implemented:
it will ONLY send emails to valid email accounts listed in the 
unnoc.conf file, so even if a hacker forges the 'from' email address to 
be your phone, it will still get sent to your phone.  The only way this 
is a security risk is if your email account get hijacked, in which case 
you have bigger things to worry about.

Most modern cell phones can only receive a txt message of 160 characters,
so if unnoc has a longer msg to send, it will get cut off at 160.  Maybe
in the future it can split it up into multiple emails...

3. Configuration

Configuration is easy, first setup an email account on your email server.
Then set the variables in the config file:

User credentials and server:

system-status {

	username = 'unnoc'
	password = 'sup3rc0mplex1tY'
	pop_server = 'pop.domain.com'

	..
	..
}

A log file is also defined to keep track of who asks and who it tells,
the default location for this is:

	$webroot/log/system_status.log

Then define who is able to check

	system-status {
		..
		..

		valid_emails {
			admin1@domain.com
			admin2@domain.com
		}
	}

To trigger it, send an email with one line in the body:

	system status


Now if admin1 sends an email to unnoc@pop.domain.com with one 'system 
status' in the body, system-status.pl will check the POP account, see 
that admin1@domain.com is asking for the system status, it will then 
read the status from MySQL and send an email to admin1@domain.com.

Security Note:

It doesn't actually send the email to the From: address, it actually 
looks at the From: address and pattern matches it to one of the 
@valid_emails, if it matches, it picks the one that it matches. 

To enable it, set the interval variable in unnoc.conf to how
often you want it to check (the more frequent the better, I do it every
1 minute)

system-status {

	interval = 1

	..
}

Future versions should support polling of temperatures, and polling
specific hosts for status.

4. Example

For example, this will enable the email address
4085551212@mobile.mycingular.com and 41515121512@mobile.mycingular.com
to see the system status.  It will also check every 2 minutes.


	system-status {
		interval = 2
		username = unnoc
		password = asdas561az
		pop_server = pop.server.domain.com

		valid_emails {
			4085551212@mobile.mycingular.com
			41515121512@mobile.mycingular.com
		}
	}

vim:tw=72:wm=1